Documentation
Everything you need to integrate uWu attestations into your dApp.
#What is uWu?
uWu is a protocol that bridges traditional fiat payment rails (like UPI, IMPS, NEFT) with blockchain smart contracts through cryptographic attestations.
When someone makes an off-chain INR payment, our oracle network verifies the bank transfer and signs a cryptographic proof that any smart contract can verify independently.
This enables trustless P2P trading, fiat on-ramps, and any use case where you need on-chain proof that real-world money moved—without custody or screenshots.
#Quick Start (JavaScript)
Install the SDK and start verifying payments in minutes.
npm install @uwu/sdk ethersimport { UwuClient, CHAIN_CONFIGS } from '@uwu/sdk'
import { Wallet } from 'ethers'
// Initialize client
const signer = new Wallet(process.env.PRIVATE_KEY!)
const client = new UwuClient(CHAIN_CONFIGS[97], signer)
// Maker: Create a trade (locks PC in escrow)
const { tradeId } = await client.createAndWaitForTrade({
taker: "0xBuyer...",
pcAmount: ethers.parseEther("100"), // 100 PC
inrAmount: 845000000n, // ₹84,500 in paisa
payeeVpa: "maker@upi",
durationSeconds: 3600
})
// Taker: After paying INR off-chain, prove and release
const result = await client.proveAndRelease(tradeId, {
payerVpa: "taker@upi",
payeeVpa: "maker@upi",
utrNumber: "412345678901",
rail: "UPI"
})
console.log("Released!", result.releaseTxHash)#Quick Start (Solidity)
Any smart contract can verify uWu attestations without using UwuEscrow.
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;
import "@uwu/contracts/lib/UwuAttestationLib.sol";
contract MyCheckout {
using UwuAttestationLib for UwuAttestationLib.Attestation;
mapping(address => bool) public authorizedOracles;
mapping(bytes32 => bool) public processedPayments;
function processPayment(
UwuAttestationLib.Attestation calldata att,
bytes calldata signature
) external {
bytes32 attHash = att.hash();
require(!processedPayments[attHash], "Already processed");
require(block.timestamp <= att.expiresAt, "Expired");
require(att.riskScore < 70, "Risk too high");
address signer = att.recoverSigner(signature);
require(authorizedOracles[signer], "Invalid oracle");
processedPayments[attHash] = true;
// Your custom logic: mint NFT, credit balance, etc.
_onPaymentVerified(msg.sender, att.inrAmount);
}
}#Oracle API Reference
HTTP endpoints for requesting and retrieving attestations.
| Endpoint | Method | Description |
|---|---|---|
| /api/attest | POST | Request attestation for a payment |
| /api/attestation/:hash | GET | Retrieve attestation by hash |
| /api/rate | GET | Get current INR/USD exchange rate |
| /api/health | GET | Check oracle status and address |
| /api/oracle/stats | GET | Oracle metrics — uptime, success rate, avg latency |
| /api/verification/consent | POST | Initiate Setu AA consent, returns consentId + redirectUrl |
| /api/setu/callback | POST | Setu notification webhook (configure in Setu console) |
POST /api/attest
{
"tradeId": "0x...",
"inrAmount": 8450000,
"usdAmount": 100000000,
"payerVpa": "buyer@upi",
"payeeVpa": "seller@upi",
"utrNumber": "412345678901",
"rail": "UPI",
"chainId": 97
}{
"attestation": {
"tradeId": "0x...",
"inrAmount": 8450000,
"payerHash": "0x...",
"payeeHash": "0x...",
"timestamp": 1709740800,
"expiresAt": 1709741400,
"evidenceHash": "0x...",
"riskScore": 12
},
"signature": "0x...",
"attestationHash": "0x...",
"riskScore": 12
}GET /api/rate
{
"inrPerUsd": 84.52,
"updatedAt": 1709740800
}GET /api/health
{
"status": "healthy",
"oracleAddress": "0x..."
}#Setu AA Verification Flow
When VERIFICATION_MODE=setu, the oracle uses Setu Account Aggregator to cryptographically verify that an INR credit appeared in the seller's bank account. uWu never holds fiat — the QR routes money directly to the seller's UPI VPA.
1. Seller creates trade + enters UPI VPA
→ Escrow locks crypto on Push Chain
2. QR generated: upi://pay?pa={sellerVpa}&am={inrAmount}&tn={tradeId}
→ Seller shares QR with buyer
3. Buyer scans QR → pays via any UPI app (GPay, PhonePe, BHIM...)
→ INR goes directly to seller's bank account (uWu never touches fiat)
4. Oracle creates Setu AA consent → buyer approves in Setu popup
→ Setu fetches DEPOSIT transactions from buyer's bank (FIP)
5. Oracle matches CREDIT by amount ± 1% + UTR number
→ Signs attestation with Ed25519 key
6. Frontend submits attestation → contract verifies oracle signature
→ Escrow auto-releases crypto to buyer#TDS Compliance (Section 194S)
Every uWu attestation is an auditable on-chain record. The Tax dashboard auto-calculates your Section 194S liability and exports Form 26QE-compatible CSV.
Section: 194S
Rate: 1% of INR amount
Trigger: per-transaction > ₹10,000
FY: April–March (India)
Example:
Trade: ₹50,000
TDS: ₹500 (1%)
Trade: ₹8,000
TDS: ₹0 (below threshold)# JSON summary
GET /api/tds?wallet=0x...
# CSV export (Form 26QE-compatible)
GET /api/tds?wallet=0x...&format=csv
Response:
{
"fy": "2025-26",
"tradeCount": 12,
"totalInrRupees": "84000.00",
"totalTdsRupees": "840.00",
"section": "194S"
}#SDK vs REST API
REST API is the stable contract: routes like POST /api/attest should stay versioned and documented for any language.
npm package @uwu/sdk is a typed, ergonomic wrapper for TypeScript/JavaScript (oracle + escrow helpers). For Python, Go, or mobile clients, call the REST API directly or generate a client from an OpenAPI spec later.
#Resources
Whitepaper
Problem, architecture, roadmap, and how uWu fits into UPI and programmable settlement.
Attestation Spec
Full technical specification for attestation structure, EIP-712 signing, and verification.
Community
X, Discord, and GitHub pointers — set NEXT_PUBLIC_UWU_SOCIAL_* in your deploy env.
GitHub Repository
Source code for contracts, SDK, oracle, and frontend. MIT licensed.
Waitlist
Get launch and integration updates (email only). Backed by Supabase from a server API route.