Debt Claims API

Submit and manage on-chain debt claims between wallets. Debt claims feed into the Credit History reputation score.

Submit Claim

POST /api/v1/debt-claims

{
  "creditorAddress": "0xCreditor...",
  "debtorAddress": "0xDebtor...",
  "claimType": "DefaultedLoan",
  "amount": 1500.50,
  "currency": "USDC",
  "description": "Defaulted on undercollateralized loan from Aave v3 on Arbitrum.",
  "evidenceTransactionHash": "0xabc123...",
  "chainId": 42161,
  "protocolName": "Aave V3"
}

Validation

Field	Rules
creditorAddress	Required, valid Ethereum address
debtorAddress	Required, valid Ethereum address
claimType	DebtClaimType enum value
amount	Required, decimal ≥ 0.000001
currency	Required, 3–5 uppercase characters (e.g., ETH, USDC, WBTC)
description	Required, 10–2,000 characters
evidenceTransactionHash	Required, valid transaction hash
chainId	Required, integer ≥ 1
protocolName	Required, max 100 characters

Response

{
  "id": "a1b2c3d4-...",
  "creditorAddress": "0xCreditor...",
  "debtorAddress": "0xDebtor...",
  "claimType": "DefaultedLoan",
  "status": "Pending",
  "amount": 1500.50,
  "currency": "USDC",
  "description": "...",
  "evidenceTransactionHash": "0xabc123...",
  "chainId": 42161,
  "protocolName": "Aave V3",
  "createdAt": "2026-02-28T12:00:00Z"
}

---

Get Claim

GET /api/v1/debt-claims/{id}

Returns the full debt claim object by GUID.

---

List Claims for Debtor

GET /api/v1/debt-claims/debtor/{address}

Response

{
  "debtorAddress": "0xDebtor...",
  "totalOutstandingDebt": 3200.75,
  "claimCount": 2,
  "claims": [
    {
      "id": "...",
      "creditorAddress": "0xCreditorA...",
      "claimType": "DefaultedLoan",
      "status": "Pending",
      "amount": 1500.50,
      "currency": "USDC",
      "protocolName": "Aave V3",
      "createdAt": "..."
    }
  ]
}

---

List Claims for Creditor

GET /api/v1/debt-claims/creditor/{address}

Response

{
  "creditorAddress": "0xCreditor...",
  "claimCount": 3,
  "claims": [...]
}

---

Dispute Claim

POST /api/v1/debt-claims/{id}/dispute

The debtor can dispute a claim filed against them.

{
  "debtorAddress": "0xDebtor...",
  "reason": "This loan was repaid in full via transaction 0xdef456 on 2026-02-20."
}

Validation

Field	Rules
debtorAddress	Required, valid Ethereum address
reason	Required, 10–2,000 characters

Response

{
  "id": "a1b2c3d4-...",
  "status": "Disputed",
  "resolutionNotes": "This loan was repaid in full...",
  "updatedAt": "2026-02-28T12:05:00Z"
}

---

Resolve Claim (Admin)

POST /api/v1/debt-claims/{id}/resolve

{
  "resolutionNotes": "Verified on-chain repayment. Claim resolved in debtor's favor."
}

Validation

Field	Rules
resolutionNotes	Required, 10–2,000 characters

Response

{
  "id": "a1b2c3d4-...",
  "status": "Resolved",
  "resolutionNotes": "...",
  "resolvedAt": "2026-02-28T12:10:00Z",
  "updatedAt": "2026-02-28T12:10:00Z"
}

---

Withdraw Claim

POST /api/v1/debt-claims/{id}/withdraw

The creditor can withdraw their own claim.

{
  "creditorAddress": "0xCreditor..."
}

Validation

Field	Rules
creditorAddress	Required, valid Ethereum address

Response

{
  "id": "a1b2c3d4-...",
  "status": "Withdrawn",
  "updatedAt": "2026-02-28T12:15:00Z",
  "resolvedAt": "2026-02-28T12:15:00Z"
}

---

Claim Lifecycle

Pending → Disputed → Resolved
   │                    ↑
   │         Admin ─────┘
   │
   └──→ Withdrawn (by creditor)

---

Impact on Reputation

Debt claims directly affect the Credit History score category:

Claim Status	Score Impact
Pending	Minor negative signal (unverified)
Disputed	Impact paused while under review
Resolved (debtor favor)	Negative impact removed
Resolved (creditor favor)	Significant negative impact
Withdrawn	No impact

Multiple unresolved claims from different creditors compound the negative effect on the debtor's Credit History score.