Disputes

Account-level dispute list (open and closed) across the caller's payments.

List disputes on the authenticated wallet's payments (open and closed)

GET /disputes

Bearer JWT (Sign-In With Ethereum)

Query parameters

• page integer

  1-based page number.

• per_page integer

  Items per page (capped at 100).

• sort string

  Comma-separated sort fields; prefix with - for descending (e.g. -created_at,status). An unsupported field is rejected with 422 invalid_sort, whose detail names the allowed set — it is never silently dropped.

• status string

  Filter by dispute status.

  One of: open, closed

Responses

• 200 Disputes (open and closed) on the caller's payments (as payer or payee).
• 401 Authentication failed.

curl

curl "https://api.rail0.xyz/disputes" \
  -H "Authorization: Bearer $RAIL0_TOKEN"

TypeScript

const res = await fetch("https://api.rail0.xyz/disputes", {
  headers: {
    Authorization: `Bearer ${process.env.RAIL0_TOKEN}`,
  },
});

if (!res.ok) {
  const { code, detail } = await res.json();
  throw new Error(`${res.status} ${code}: ${detail}`);
}
const data = await res.json();

Ruby

require "json"
require "net/http"

uri = URI("https://api.rail0.xyz/disputes")
req = Net::HTTP::Get.new(uri)
req["Authorization"] = "Bearer #{ENV.fetch("RAIL0_TOKEN")}"

res = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https") { |http| http.request(req) }
raise "#{res.code}: #{res.body}" unless res.is_a?(Net::HTTPSuccess)
data = JSON.parse(res.body)

Go

package main

import (
  "fmt"
  "io"
  "net/http"
  "os"
)

func main() {
  url := "https://api.rail0.xyz/disputes"
  req, err := http.NewRequest(http.MethodGet, url, nil)
  if err != nil {
    panic(err)
  }
  req.Header.Set("Authorization", "Bearer "+os.Getenv("RAIL0_TOKEN"))

  res, err := http.DefaultClient.Do(req)
  if err != nil {
    panic(err)
  }
  defer res.Body.Close()

  data, err := io.ReadAll(res.Body)
  if err != nil {
    panic(err)
  }
  fmt.Println(res.Status, string(data))
}

Response 200

[
  {
    "id": "5f0c2b1e-8d4a-4f6e-9a7b-2c3d4e5f6a7b",
    "payment_id": "5f0c2b1e-8d4a-4f6e-9a7b-2c3d4e5f6a7b",
    "status": "open",
    "reason": "string",
    "reason_code": "not_received",
    "reason_description": "string",
    "opened_block": null,
    "opened_at": "2026-10-01T12:00:00Z",
    "closed_by": "payer",
    "close_reason": null,
    "close_reason_code": "resolved_with_merchant",
    "close_reason_description": null,
    "closed_block": null,
    "closed_at": null,
    "payment": {
      "id": "5f0c2b1e-8d4a-4f6e-9a7b-2c3d4e5f6a7b",
      "contract_id": "0f1e2d3c-4b5a-4968-8776-655443322110",
      "chain_id": 84532,
      "rail0_id": "0x9c2f0d4e7b1a3c5e8f6d2b4a1c3e5f7d9b0a2c4e6f8d1b3a5c7e9f0d2b4a6c8e",
      "status": "authorized",
      "mode": "authorize",
      "amount": "10500000",
      "capturable_amount": "10500000",
      "refundable_amount": "10500000",
      "config_hash": "0x4e3a3754410177e6937ef1f84bba68ea139e8d1a2258c5f85db9f1cd715a1bdd",
      "payer": "0x8ba1f109551bD432803012645Ac136ddd64DBA72",
      "payee": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F",
      "token": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
      "decimals": 6,
      "authorization_expiry": 1791633600,
      "refund_expiry": 1794225600,
      "escrow_stranded": false,
      "escrow_returnable_at": null,
      "disputed": false,
      "in_flight": false,
      "last_error_code": null,
      "last_error_message": null,
      "description": "Order #1042",
      "metadata": {
        "order_id": "ord_1042"
      },
      "signed_at": null,
      "created_at": "2026-10-01T12:00:00Z",
      "updated_at": "2026-10-01T12:00:00Z"
    }
  }
]