Disputes API

Submit and manage disputes for incorrect or outdated reputation scores.

Submit a Dispute

POST /api/v1/dispute

{
  "walletAddress": "0x1234...",
  "category": "DEFI_LENDING",
  "reason": "IncorrectData",
  "description": "My Aave v3 positions on Arbitrum are not being counted.",
  "evidence": "https://arbiscan.io/tx/0xabc..."
}

Validation

Field	Rules
walletAddress	Required, valid Ethereum address
category	ScoreCategory enum value
reason	DisputeReason enum value
description	Required, 10–2,000 characters
evidence	Optional, max 5,000 characters

Dispute Reasons

InaccurateScore, MissingActivity, IncorrectCategory, DataOutdated, WrongWallet, FraudulentData, ComplianceError, Other

Response

{
  "id": "a1b2c3d4-...",
  "walletAddress": "0x1234...",
  "category": "DEFI_LENDING",
  "reason": "IncorrectData",
  "status": "Pending",
  "description": "My Aave v3 positions on Arbitrum are not being counted.",
  "evidence": "https://arbiscan.io/tx/0xabc...",
  "createdAt": "2026-02-27T12:00:00Z"
}

---

Get Dispute

GET /api/v1/dispute/{id}

Returns the full dispute object by GUID.

---

List Disputes for Wallet

GET /api/v1/dispute/wallet/{address}

Response

{
  "address": "0x1234...",
  "count": 2,
  "disputes": [...]
}

---

Update Dispute Status

PUT /api/v1/dispute/{id}/status

Admin endpoint for updating dispute status.

{
  "status": "Resolved",
  "resolutionNotes": "Score recalculated with Arbitrum data.",
  "resolvedBy": "admin@crowdproof.id",
  "revisedScore": 780
}

Validation

Field	Rules
status	DisputeStatus enum value
resolutionNotes	Optional, max 2,000 characters
resolvedBy	Optional, max 200 characters
revisedScore	Optional, integer 0–1,000

---

Escalate Dispute

POST /api/v1/dispute/{id}/escalate

Escalates a dispute to on-chain governance when the off-chain resolution is unsatisfactory.

{
  "reason": "Unresolved after 14 days, original data still incorrect."
}

Validation

Field	Rules
reason	Required, 10–2,000 characters

Escalated disputes are reviewed by GOVERNANCE_ROLE holders via the ReputationOracle contract.

---

Withdraw Dispute

POST /api/v1/dispute/{id}/withdraw

{
  "walletAddress": "0x1234..."
}

Only the original submitter can withdraw a dispute. Returns 204 No Content equivalent on success.

---

Dispute Lifecycle

Pending → Under Review → Evidence Requested → Resolved / Rejected
                                               ↓
                                           Escalated (on-chain governance)