Coinbax API

disputes

View as Markdown

Get all disputes for platform

GET/api/v1/disputesBearer token

Query parameters

statusenum
Filter by dispute status
"open" · "under_review" · "pending_votes" · "in_arbitration" · "resolved"

Responses

200Disputes retrieved successfully

array of DisputeResponseDto

idstringrequired
transactionIdstringrequired
initiatedByenumrequired"sender" · "receiver"
currentTierenumrequired"tier_1_smart_contract" · "tier_2_peer_review" · "tier_3_arbitration"
statusenumrequired"open" · "under_review" · "pending_votes" · "in_arbitration" · "resolved"
reasonstringrequired
tier1CompletedAtobject
object
tier2CompletedAtobject
object
resolvedAtobject
object
outcomeenum"favor_sender" · "favor_receiver" · "partial_refund"
resolutionReasonobject
object
refundPercentageobject
object
metadataobject
object
createdAtstring (date-time)required
updatedAtstring (date-time)required
evidencearray of EvidenceResponseDto
array of EvidenceResponseDto
idstringrequired
disputeIdstringrequired
submittedBystringrequired
typestringrequired
titlestringrequired
descriptionobject
object
contentobject
object
fileUrlobject
object
fileHashobject
object
isEncryptedbooleanrequired
metadataobject
object
createdAtstring (date-time)required

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "transactionId": "550e8400-e29b-41d4-a716-446655440001",
    "initiatedBy": "sender",
    "currentTier": "tier_1_smart_contract",
    "status": "open",
    "reason": "Product not as described",
    "tier1CompletedAt": "2024-01-15T10:30:00Z",
    "tier2CompletedAt": "2024-01-16T10:30:00Z",
    "resolvedAt": "2024-01-17T10:30:00Z",
    "outcome": "favor_sender",
    "resolutionReason": "Evidence clearly shows product defect",
    "refundPercentage": 50,
    "metadata": {},
    "createdAt": "2024-01-15T10:00:00Z",
    "updatedAt": "2024-01-15T10:30:00Z",
    "evidence": [
      {
        "id": "string",
        "disputeId": "string",
        "submittedBy": "string",
        "type": "string",
        "title": "string",
        "description": {},
        "content": {},
        "fileUrl": {},
        "fileHash": {},
        "isEncrypted": true,
        "metadata": {},
        "createdAt": "2026-01-15T12:00:00.000Z"
      }
    ]
  }
]

curlNode.js

curl https://api-staging.coinbax.com/api/v1/disputes \
  -H "Authorization: Bearer $ACCESS_TOKEN"

const response = await fetch('https://api-staging.coinbax.com/api/v1/disputes', {
  headers: {
    'Authorization': `Bearer ${process.env.ACCESS_TOKEN}`,
  },
});
const result = await response.json();

Create a new dispute for a transaction

POST/api/v1/disputesBearer token

Request body

transactionIdstringrequired
Transaction ID to dispute
initiatedByenumrequired"sender" · "receiver"
Who is initiating the dispute
reasonstringrequired
Reason for the dispute
metadataobject
Additional metadata
object
Additional metadata

Responses

201Dispute created successfully

idstringrequired
transactionIdstringrequired
initiatedByenumrequired"sender" · "receiver"
currentTierenumrequired"tier_1_smart_contract" · "tier_2_peer_review" · "tier_3_arbitration"
statusenumrequired"open" · "under_review" · "pending_votes" · "in_arbitration" · "resolved"
reasonstringrequired
tier1CompletedAtobject
object
tier2CompletedAtobject
object
resolvedAtobject
object
outcomeenum"favor_sender" · "favor_receiver" · "partial_refund"
resolutionReasonobject
object
refundPercentageobject
object
metadataobject
object
createdAtstring (date-time)required
updatedAtstring (date-time)required
evidencearray of EvidenceResponseDto
array of EvidenceResponseDto
idstringrequired
disputeIdstringrequired
submittedBystringrequired
typestringrequired
titlestringrequired
descriptionobject
object
contentobject
object
fileUrlobject
object
fileHashobject
object
isEncryptedbooleanrequired
metadataobject
object
createdAtstring (date-time)required

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "transactionId": "550e8400-e29b-41d4-a716-446655440001",
  "initiatedBy": "sender",
  "currentTier": "tier_1_smart_contract",
  "status": "open",
  "reason": "Product not as described",
  "tier1CompletedAt": "2024-01-15T10:30:00Z",
  "tier2CompletedAt": "2024-01-16T10:30:00Z",
  "resolvedAt": "2024-01-17T10:30:00Z",
  "outcome": "favor_sender",
  "resolutionReason": "Evidence clearly shows product defect",
  "refundPercentage": 50,
  "metadata": {},
  "createdAt": "2024-01-15T10:00:00Z",
  "updatedAt": "2024-01-15T10:30:00Z",
  "evidence": [
    {
      "id": "string",
      "disputeId": "string",
      "submittedBy": "string",
      "type": "string",
      "title": "string",
      "description": {},
      "content": {},
      "fileUrl": {},
      "fileHash": {},
      "isEncrypted": true,
      "metadata": {},
      "createdAt": "2026-01-15T12:00:00.000Z"
    }
  ]
}

400Invalid request data or transaction not disputable

Response follows the unified success / data / meta / error envelope.

404Transaction not found

Response follows the unified success / data / meta / error envelope.

409Dispute already exists for this transaction

Response follows the unified success / data / meta / error envelope.

curlNode.js

curl -X POST https://api-staging.coinbax.com/api/v1/disputes \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "transactionId": "550e8400-e29b-41d4-a716-446655440000",
  "initiatedBy": "sender",
  "reason": "Product not as described",
  "metadata": {
    "category": "product_quality"
  }
}'

const response = await fetch('https://api-staging.coinbax.com/api/v1/disputes', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.ACCESS_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "transactionId": "550e8400-e29b-41d4-a716-446655440000",
    "initiatedBy": "sender",
    "reason": "Product not as described",
    "metadata": {
      "category": "product_quality"
    }
  }),
});
const result = await response.json();

Get dispute by ID

GET/api/v1/disputes/{id}Bearer token

Path parameters

idstringrequired

Responses

200Dispute found

idstringrequired
transactionIdstringrequired
initiatedByenumrequired"sender" · "receiver"
currentTierenumrequired"tier_1_smart_contract" · "tier_2_peer_review" · "tier_3_arbitration"
statusenumrequired"open" · "under_review" · "pending_votes" · "in_arbitration" · "resolved"
reasonstringrequired
tier1CompletedAtobject
object
tier2CompletedAtobject
object
resolvedAtobject
object
outcomeenum"favor_sender" · "favor_receiver" · "partial_refund"
resolutionReasonobject
object
refundPercentageobject
object
metadataobject
object
createdAtstring (date-time)required
updatedAtstring (date-time)required
evidencearray of EvidenceResponseDto
array of EvidenceResponseDto
idstringrequired
disputeIdstringrequired
submittedBystringrequired
typestringrequired
titlestringrequired
descriptionobject
object
contentobject
object
fileUrlobject
object
fileHashobject
object
isEncryptedbooleanrequired
metadataobject
object
createdAtstring (date-time)required

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "transactionId": "550e8400-e29b-41d4-a716-446655440001",
  "initiatedBy": "sender",
  "currentTier": "tier_1_smart_contract",
  "status": "open",
  "reason": "Product not as described",
  "tier1CompletedAt": "2024-01-15T10:30:00Z",
  "tier2CompletedAt": "2024-01-16T10:30:00Z",
  "resolvedAt": "2024-01-17T10:30:00Z",
  "outcome": "favor_sender",
  "resolutionReason": "Evidence clearly shows product defect",
  "refundPercentage": 50,
  "metadata": {},
  "createdAt": "2024-01-15T10:00:00Z",
  "updatedAt": "2024-01-15T10:30:00Z",
  "evidence": [
    {
      "id": "string",
      "disputeId": "string",
      "submittedBy": "string",
      "type": "string",
      "title": "string",
      "description": {},
      "content": {},
      "fileUrl": {},
      "fileHash": {},
      "isEncrypted": true,
      "metadata": {},
      "createdAt": "2026-01-15T12:00:00.000Z"
    }
  ]
}

404Dispute not found

Response follows the unified success / data / meta / error envelope.

curlNode.js

curl https://api-staging.coinbax.com/api/v1/disputes/<id> \
  -H "Authorization: Bearer $ACCESS_TOKEN"

const response = await fetch('https://api-staging.coinbax.com/api/v1/disputes/<id>', {
  headers: {
    'Authorization': `Bearer ${process.env.ACCESS_TOKEN}`,
  },
});
const result = await response.json();

Escalate dispute to next tier

POST/api/v1/disputes/{id}/escalateBearer token

Path parameters

idstringrequired

Responses

200Dispute escalated successfully

idstringrequired
transactionIdstringrequired
initiatedByenumrequired"sender" · "receiver"
currentTierenumrequired"tier_1_smart_contract" · "tier_2_peer_review" · "tier_3_arbitration"
statusenumrequired"open" · "under_review" · "pending_votes" · "in_arbitration" · "resolved"
reasonstringrequired
tier1CompletedAtobject
object
tier2CompletedAtobject
object
resolvedAtobject
object
outcomeenum"favor_sender" · "favor_receiver" · "partial_refund"
resolutionReasonobject
object
refundPercentageobject
object
metadataobject
object
createdAtstring (date-time)required
updatedAtstring (date-time)required
evidencearray of EvidenceResponseDto
array of EvidenceResponseDto
idstringrequired
disputeIdstringrequired
submittedBystringrequired
typestringrequired
titlestringrequired
descriptionobject
object
contentobject
object
fileUrlobject
object
fileHashobject
object
isEncryptedbooleanrequired
metadataobject
object
createdAtstring (date-time)required

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "transactionId": "550e8400-e29b-41d4-a716-446655440001",
  "initiatedBy": "sender",
  "currentTier": "tier_1_smart_contract",
  "status": "open",
  "reason": "Product not as described",
  "tier1CompletedAt": "2024-01-15T10:30:00Z",
  "tier2CompletedAt": "2024-01-16T10:30:00Z",
  "resolvedAt": "2024-01-17T10:30:00Z",
  "outcome": "favor_sender",
  "resolutionReason": "Evidence clearly shows product defect",
  "refundPercentage": 50,
  "metadata": {},
  "createdAt": "2024-01-15T10:00:00Z",
  "updatedAt": "2024-01-15T10:30:00Z",
  "evidence": [
    {
      "id": "string",
      "disputeId": "string",
      "submittedBy": "string",
      "type": "string",
      "title": "string",
      "description": {},
      "content": {},
      "fileUrl": {},
      "fileHash": {},
      "isEncrypted": true,
      "metadata": {},
      "createdAt": "2026-01-15T12:00:00.000Z"
    }
  ]
}

400Cannot escalate resolved dispute or already at highest tier

Response follows the unified success / data / meta / error envelope.

404Dispute not found

Response follows the unified success / data / meta / error envelope.

curlNode.js

curl -X POST https://api-staging.coinbax.com/api/v1/disputes/<id>/escalate \
  -H "Authorization: Bearer $ACCESS_TOKEN"

const response = await fetch('https://api-staging.coinbax.com/api/v1/disputes/<id>/escalate', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.ACCESS_TOKEN}`,
  },
});
const result = await response.json();

Submit evidence for a dispute

POST/api/v1/disputes/{id}/evidenceBearer token

Path parameters

idstringrequired

Request body

submittedByenumrequired"sender" · "receiver"
Who is submitting the evidence
typeenumrequired"text" · "image" · "document" · "screenshot" · "communication_log" · "other"
Type of evidence
titlestringrequired
Title of the evidence
descriptionstring
Description of the evidence
contentstring
Text content (for text evidence)
fileUrlstring
File URL (IPFS or storage)
fileHashstring
Hash of the file for verification
isEncryptedboolean
Whether the evidence is encrypted
metadataobject
Additional metadata
object
Additional metadata

Responses

201Evidence submitted successfully

idstringrequired
disputeIdstringrequired
submittedBystringrequired
typestringrequired
titlestringrequired
descriptionobject
object
contentobject
object
fileUrlobject
object
fileHashobject
object
isEncryptedbooleanrequired
metadataobject
object
createdAtstring (date-time)required

{
  "id": "string",
  "disputeId": "string",
  "submittedBy": "string",
  "type": "string",
  "title": "string",
  "description": {},
  "content": {},
  "fileUrl": {},
  "fileHash": {},
  "isEncrypted": true,
  "metadata": {},
  "createdAt": "2026-01-15T12:00:00.000Z"
}

400Cannot submit evidence to resolved dispute

Response follows the unified success / data / meta / error envelope.

404Dispute not found

Response follows the unified success / data / meta / error envelope.

curlNode.js

curl -X POST https://api-staging.coinbax.com/api/v1/disputes/<id>/evidence \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "submittedBy": "sender",
  "type": "screenshot",
  "title": "Screenshot of product defect",
  "description": "This shows the damaged packaging upon delivery",
  "content": "Conversation log...",
  "fileUrl": "ipfs://QmXyz123...",
  "fileHash": "0xabc123...",
  "isEncrypted": true,
  "metadata": {
    "fileSize": 1024000,
    "mimeType": "image/png"
  }
}'

const response = await fetch('https://api-staging.coinbax.com/api/v1/disputes/<id>/evidence', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.ACCESS_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "submittedBy": "sender",
    "type": "screenshot",
    "title": "Screenshot of product defect",
    "description": "This shows the damaged packaging upon delivery",
    "content": "Conversation log...",
    "fileUrl": "ipfs://QmXyz123...",
    "fileHash": "0xabc123...",
    "isEncrypted": true,
    "metadata": {
      "fileSize": 1024000,
      "mimeType": "image/png"
    }
  }),
});
const result = await response.json();

Resolve a dispute

POST/api/v1/disputes/{id}/resolveBearer token

Path parameters

idstringrequired

Request body

outcomeenumrequired"favor_sender" · "favor_receiver" · "partial_refund"
Outcome of the dispute
resolutionReasonstringrequired
Reason for the resolution
refundPercentagenumber
Refund percentage (0-100) if partial refund

Responses

200Dispute resolved successfully

idstringrequired
transactionIdstringrequired
initiatedByenumrequired"sender" · "receiver"
currentTierenumrequired"tier_1_smart_contract" · "tier_2_peer_review" · "tier_3_arbitration"
statusenumrequired"open" · "under_review" · "pending_votes" · "in_arbitration" · "resolved"
reasonstringrequired
tier1CompletedAtobject
object
tier2CompletedAtobject
object
resolvedAtobject
object
outcomeenum"favor_sender" · "favor_receiver" · "partial_refund"
resolutionReasonobject
object
refundPercentageobject
object
metadataobject
object
createdAtstring (date-time)required
updatedAtstring (date-time)required
evidencearray of EvidenceResponseDto
array of EvidenceResponseDto
idstringrequired
disputeIdstringrequired
submittedBystringrequired
typestringrequired
titlestringrequired
descriptionobject
object
contentobject
object
fileUrlobject
object
fileHashobject
object
isEncryptedbooleanrequired
metadataobject
object
createdAtstring (date-time)required

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "transactionId": "550e8400-e29b-41d4-a716-446655440001",
  "initiatedBy": "sender",
  "currentTier": "tier_1_smart_contract",
  "status": "open",
  "reason": "Product not as described",
  "tier1CompletedAt": "2024-01-15T10:30:00Z",
  "tier2CompletedAt": "2024-01-16T10:30:00Z",
  "resolvedAt": "2024-01-17T10:30:00Z",
  "outcome": "favor_sender",
  "resolutionReason": "Evidence clearly shows product defect",
  "refundPercentage": 50,
  "metadata": {},
  "createdAt": "2024-01-15T10:00:00Z",
  "updatedAt": "2024-01-15T10:30:00Z",
  "evidence": [
    {
      "id": "string",
      "disputeId": "string",
      "submittedBy": "string",
      "type": "string",
      "title": "string",
      "description": {},
      "content": {},
      "fileUrl": {},
      "fileHash": {},
      "isEncrypted": true,
      "metadata": {},
      "createdAt": "2026-01-15T12:00:00.000Z"
    }
  ]
}

400Dispute already resolved or invalid resolution data

Response follows the unified success / data / meta / error envelope.

404Dispute not found

Response follows the unified success / data / meta / error envelope.

curlNode.js

curl -X POST https://api-staging.coinbax.com/api/v1/disputes/<id>/resolve \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "outcome": "favor_sender",
  "resolutionReason": "Evidence clearly shows product defect",
  "refundPercentage": 50
}'

const response = await fetch('https://api-staging.coinbax.com/api/v1/disputes/<id>/resolve', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.ACCESS_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "outcome": "favor_sender",
    "resolutionReason": "Evidence clearly shows product defect",
    "refundPercentage": 50
  }),
});
const result = await response.json();