rail0-sdk 1.0.0

data/lib/rail0/request.rb

@@ -0,0 +1,211 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "uri"
+require "forwardable"
+require_relative "api_error"
+require_relative "backoff"
+require_relative "default_logger"
+
+module Rail0
+  # @!visibility private
+  # Executes one logical call against the gateway: builds the URL, retries on
+  # network errors per the client's max_retries/retry_delay, translates non-2xx
+  # responses into Rail0::ApiError, parses the body (including the paginated
+  # {data, meta} envelope), and logs every attempt. One instance per call.
+  class Request
+    extend Forwardable
+
+    ERRORS = [
+      SocketError, Errno::ECONNREFUSED, Errno::ETIMEDOUT,
+      Net::OpenTimeout, Net::ReadTimeout, OpenSSL::SSL::SSLError
+    ].freeze
+
+    TYPES = { get: Net::HTTP::Get, post: Net::HTTP::Post,
+              put: Net::HTTP::Put, patch: Net::HTTP::Patch,
+              delete: Net::HTTP::Delete }.freeze
+
+    def_delegators :client, :base_url, :headers, :timeout, :logger, :max_retries, :retry_delay,
+                   :retry_on_429, :retry_after_cap
+
+    attr_reader :client, :method, :path, :body, :paginated, :extra_headers
+
+    def initialize(client:, method:, path:, body:, paginated:, extra_headers:)
+      @client        = client
+      @method        = method
+      @path          = path
+      @body          = body
+      @paginated     = paginated
+      @extra_headers = extra_headers
+      freeze
+    end
+
+    def call
+      url = "#{base_url}#{path}"
+      response, duration_ms, attempt = with_retries(url) { perform(url) }
+
+      unless response.is_a?(Net::HTTPSuccess)
+        error_body = parse_error_body(response)
+        api_error  = ApiError.new(response.code.to_i, error_code(error_body),
+                                  error_message(error_body, response), title: error_body[:title],
+                                                                       retry_after: retry_after_seconds(response))
+        logger.call(LogEntry.new(
+                      method: method.to_s.upcase, url: url, duration_ms: duration_ms, attempt: attempt,
+                      request_body: body, status: response.code.to_i, response_body: error_body, error: api_error
+                    ))
+        raise api_error
+      end
+
+      body_data = parse_body(response)
+      result    = paginated ? { data: body_data, meta: page_meta(response) } : body_data
+      logger.call(LogEntry.new(
+                    method: method.to_s.upcase, url: url, duration_ms: duration_ms, attempt: attempt,
+                    request_body: body, status: response.code.to_i, response_body: result
+                  ))
+      result
+    end
+
+    private
+
+    # One loop for the two things worth retrying, which fail in different ways: a network
+    # error raises, a rate limit comes back as a perfectly good 429 response.
+    #
+    # A 429 is the one status this SDK retries, and the reason is not that it is common.
+    # The gateway rejects it in middleware (Rack::Attack), BEFORE the request reaches the
+    # application — so nothing was executed, and retrying carries no risk of doing the
+    # work twice. That is not true of a 502 or a timeout on, say, a capture, where the
+    # broadcast may already be in flight. Which is why the method does not matter here and
+    # a POST is retried like a GET.
+    #
+    # The sleep is on the CALLING thread. There is no thread pool in this SDK and no
+    # promise to wait on: a job that turns retry_on_429 on is choosing to block.
+    def with_retries(url)
+      attempt = 1
+      loop do
+        start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        begin
+          response = yield
+        rescue *ERRORS => e
+          will_retry = attempt <= max_retries
+          logger.call(LogEntry.new(
+                        method: method.to_s.upcase, url: url, duration_ms: elapsed_ms(start),
+                        attempt: attempt, request_body: body, error: e, will_retry: will_retry
+                      ))
+          raise unless will_retry
+
+          attempt += 1
+          sleep(retry_delay * (2**(attempt - 2)))
+          next
+        end
+
+        return [response, elapsed_ms(start), attempt] unless retry_throttled?(response, attempt)
+
+        delay = Backoff.throttle_delay(
+          retry_after: response["retry-after"], attempt: attempt,
+          base: retry_delay, cap: retry_after_cap
+        )
+        logger.call(LogEntry.new(
+                      method: method.to_s.upcase, url: url, duration_ms: elapsed_ms(start), attempt: attempt,
+                      request_body: body, status: response.code.to_i,
+                      response_body: parse_error_body(response), will_retry: true
+                    ))
+        attempt += 1
+        sleep(delay)
+      end
+    end
+
+    # Whether this response is a rate limit the client opted into retrying, and whether
+    # there is budget left.
+    #
+    # `max_retries` is what bounds it, except that its default is 0 — so requiring both
+    # flags would make retry_on_429 a silent no-op. One retry is the floor when the
+    # caller asked for the behaviour at all.
+    def retry_throttled?(response, attempt)
+      return false unless retry_on_429 && response.code.to_i == 429
+
+      attempt <= [max_retries, 1].max
+    end
+
+    # @return [Integer, nil] the Retry-After header as whole seconds, when it is a
+    #   positive number. HTTP-date form is not parsed: the gateway never sends one, and
+    #   guessing at a date would be worse than admitting we have no instruction.
+    def retry_after_seconds(response)
+      seconds = Backoff.positive_number(response["retry-after"])
+      seconds&.round
+    end
+
+    def parse_body(response)
+      raw = response.body
+      return nil if raw.nil? || raw.strip.empty?
+
+      JSON.parse(raw, symbolize_names: true)
+    end
+
+    def page_meta(response)
+      {
+        page:        response["x-page"].to_i,
+        per_page:    response["x-per-page"].to_i,
+        total:       response["x-total-count"].to_i,
+        # Zero for an empty collection: "no pages" is what there are, so a pager
+        # rendered off this renders none. (rail0-gateway#242)
+        total_pages: response["x-total-pages"].to_i,
+        links:       page_links(response["link"])
+      }.freeze
+    end
+
+    # RFC 8288 Link into { first:, prev:, next:, last: }. `first`/`last` are always
+    # sent, `prev`/`next` only where they exist, and the header is ABSENT entirely on
+    # an empty collection — so an empty hash here means "no pages", not "unparsed".
+    #
+    # The URIs are RELATIVE (path + query) and resolve against the URL you requested:
+    # the gateway emits them that way so they cannot advertise the wrong scheme
+    # through a TLS-terminating proxy.
+    def page_links(raw)
+      return {}.freeze if raw.nil? || raw.empty?
+
+      raw.scan(/<([^>]+)>\s*;\s*rel="([^"]+)"/)
+         .each_with_object({}) { |(uri, rel), acc| acc[rel.to_sym] = uri }
+         .freeze
+    end
+
+    def perform(url)
+      uri  = URI.parse(url)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl       = uri.scheme == "https"
+      http.open_timeout  = timeout
+      http.read_timeout  = timeout
+      http.write_timeout = timeout
+
+      req_class = TYPES.fetch(method, Net::HTTP::Post)
+      req = req_class.new(uri.request_uri)
+      headers.merge(extra_headers).each { |k, v| req[k] = v }
+      req.body = body.to_json if body && %i[post put patch].include?(method)
+
+      http.request(req)
+    end
+
+    def parse_error_body(response)
+      JSON.parse(response.body, symbolize_names: true)
+    rescue JSON::ParserError, TypeError
+      {}
+    end
+
+    # The gateway answers exactly code/title/detail, having DELETED the older aliases
+    # rather than dual-sending them (#252) — `status` (the wider family), `message`
+    # (equal to detail) and Grape's `error`. The chains that read them could only ever
+    # find absent keys, so each collapses to the one field there is. The bare HTTP status
+    # stays as the last resort for a body with no text at all.
+    def error_code(body)
+      body[:code]
+    end
+
+    def error_message(body, response = nil)
+      body[:detail] || (response && "HTTP #{response.code}")
+    end
+
+    def elapsed_ms(start)
+      (Process.clock_gettime(Process::CLOCK_MONOTONIC) - start) * 1000
+    end
+  end
+end

data/lib/rail0/resources/accounts.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Rail0
+  module Resources
+    # The merchant account itself (requires JWT).
+    #
+    # One method, and that is the whole surface by design: the gateway guards
+    # `/accounts/:account_id` with an ownership check — a JWT whose account matches the
+    # path — so a caller can only ever read its OWN account. There is no endpoint for
+    # reading another merchant's, and an id that is not an account answers 404 exactly as
+    # another account's id does, so the pair cannot be used to learn whether an account
+    # exists.
+    #
+    # The account's wallets are a collection under the same path and live on
+    # {Resources::Wallets}; buyer-facing discovery of what a merchant accepts lives on
+    # {Resources::PaymentMethods}.
+    class Accounts
+      attr_reader :http
+
+      def initialize(http)
+        @http = http
+        freeze
+      end
+
+      # The account's own profile.
+      # @param account_id [String] The account UUID — must be the one this JWT belongs to.
+      # @return [Hash] `id`, `name`, `email`, `created_at`, `updated_at`. `email` is part of
+      #   the response because the holder is this endpoint's only possible caller: it is a
+      #   merchant reading its own contact address, never another's.
+      def get(account_id)
+        http.get("/accounts/#{account_id}")
+      end
+    end
+  end
+end

data/lib/rail0/resources/analytics.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require_relative "query"
+
+module Rail0
+  module Resources
+    # Account-scoped payment analytics (requires JWT — a buyer's account-less token is
+    # refused with `account_required`). Every endpoint takes the same filters, so the
+    # three views answer one question at different resolutions: a total, a series over
+    # time, a split by dimension.
+    #
+    # Money is never summed across units, and each view obeys that differently: `summary`
+    # and `breakdown` GROUP by (token, chain) and always report volume, while `timeseries`
+    # can only carry volume when a query pins both `token` and `chain_id` — a bucket is one
+    # number, so it has nowhere to keep two tokens apart. Gas follows the same rule per
+    # chain: it is denominated in the chain's native token, so it is reported per chain and
+    # never totalled.
+    #
+    # These methods return the parsed JSON as-is, so the keys documented below are the
+    # contract this SDK offers — there is no typed wrapper standing between them and the
+    # gateway.
+    class Analytics
+      include Query
+
+      FILTERS = %i[mode status token chain_id from to].freeze
+
+      attr_reader :http
+
+      def initialize(http)
+        @http = http
+        freeze
+      end
+
+      # Totals for the account's payments.
+      # @param mode [String, nil] "authorize" or "charge".
+      # @param status [String, nil] A payment status, e.g. "captured".
+      # @param token [String, nil] Token address (0x…).
+      # @param chain_id [Integer, nil] Chain ID. Pass nil or 0 for all chains.
+      # @param from [String, nil] ISO-8601 — payments created at/after this time.
+      # @param to [String, nil] ISO-8601 — payments created at/before this time.
+      # @return [Hash] the headline KPIs:
+      #   * `orders`, `disputed` — counts.
+      #   * `refund_rate`, `dispute_rate` — fractions in [0,1], per ORDER.
+      #   * `failed_rate` — per resolved TRANSACTION, not per order: one order can carry
+      #     several attempts, and a retried capture that eventually confirms is what this
+      #     surfaces.
+      #   * `by_status` — status => count, for the statuses present.
+      #   * `volume` — one row per (token, chain) with base-unit integer strings: `gross`
+      #     authorized, `settled` held by the payee net of refunds, `escrowed` still in
+      #     escrow, and gross `captured`/`refunded` from the confirmed transactions. The
+      #     first two say where the money IS, the last two what HAPPENED.
+      #   * `failures` — why the merchant's transactions failed, commonest first: one row of
+      #     `code` (the same catalogue an error body uses, or "unknown") and `transactions`.
+      #     `failed_rate` says how much fails; this says what to act on — a revert is a state
+      #     problem (an amount above the residual, a closed window) while a rejection that
+      #     never reached the chain is a wallet problem (no gas money, a used nonce).
+      #   * `gas` — one row per CHAIN, in that chain's NATIVE token (`decimals` 18, never
+      #     the payment token): `spent` on confirmed transactions, `wasted` burned by
+      #     on-chain reverts, `confirmed`/`failed` counts, and `orders` — the payments
+      #     behind the figures, which is the denominator for the average cost of an order.
+      #     Never sum across chains: Base ETH and Polygon POL are different currencies. Each
+      #     row also carries `confirmation_secs`: mean seconds from broadcast to confirmation
+      #     on that chain, weighted by its confirmations, and nil when none confirmed — not
+      #     0, which would read as instant. Per chain, because a chain that wants 60
+      #     confirmations and one that wants 4 are not comparable.
+      #   * `gas_by_status`, `gas_by_operation` — those same rows regrouped, each carrying
+      #     a `key` (the status / the operation). Every cut adds back up to its chain's
+      #     `gas` row. `orders` is null on the operation cut, since one order spans several
+      #     operations. The status cut is a SNAPSHOT: status moves, so an authorize's gas
+      #     sits under "authorized" until the payment is captured and then under
+      #     "captured".
+      #
+      #   Gas covers only the operations the merchant broadcasts — dispute/close_dispute
+      #   are the buyer's cost on-chain and release records no sender, so both are out.
+      def summary(**filters)
+        http.get("/analytics/summary#{build_query(**only_filters(filters))}")
+      end
+
+      # The account's payment count per time bucket, oldest first.
+      # @param interval [String, nil] "day" (default), "week" or "month". Anything else is
+      #   rejected by the gateway — there is no hourly bucket.
+      # @return [Array<Hash>] `bucket` (ISO-8601 start), `orders`, and `volume` — a
+      #   base-unit string only when BOTH token and chain_id are filtered, else null.
+      def timeseries(interval: nil, **filters)
+        http.get("/analytics/timeseries#{build_query(**only_filters(filters), interval: interval)}")
+      end
+
+      # The account's payments aggregated by one dimension.
+      # @param by [String] Required — "token", "chain", "mode", "status" or "operation".
+      # @return [Array<Hash>] one row per group: `key` (the dimension value) and `orders`.
+      #   token/chain rows also carry `token`, `chain_id`, `decimals` and `volume`;
+      #   mode/status rows leave those null, since summing money across tokens would add
+      #   different currencies. An `operation` row groups the merchant's own CONFIRMED
+      #   transactions rather than payments, so it reports both counts: `transactions` is how
+      #   often the operation ran — a partial capture runs several times on one order — and
+      #   `orders` is how many orders it touched.
+      def breakdown(by:, **filters)
+        raise ArgumentError, "by is required (token, chain, mode or status)" if by.nil? || by.to_s.empty?
+
+        http.get("/analytics/breakdown#{build_query(**only_filters(filters), by: by)}")
+      end
+
+      private
+
+      def only_filters(filters)
+        picked = filters.slice(*FILTERS)
+        picked[:chain_id] = nil if picked[:chain_id] == 0
+        picked
+      end
+    end
+  end
+end

data/lib/rail0/resources/auth.rb

@@ -0,0 +1,192 @@
+# frozen_string_literal: true
+
+module Rail0
+  module Resources
+    # SIWE (Sign-In With Ethereum) authentication.
+    #
+    # {nonce} and {verify} are plain HTTP calls with no extra dependencies.
+    # {login} runs the full handshake and needs the optional signing gems
+    # ('eth' and 'siwe-rb'), which are required lazily so `require "rail0"`
+    # works without them.
+    #
+    # The JWT returned by {verify}/{login} is NOT stored on the client — pass it
+    # yourself on subsequent requests via the client's +headers+:
+    #   auth = client.auth.login(private_key: "0x...", domain: "api.rail0.xyz")
+    #   client = Rail0::Client.new(base_url: BASE, headers: { "Authorization" => "Bearer #{auth[:token]}" })
+    class Auth
+      # The SIWE statement for signing in — POST /auth. Kept identical to
+      # rail0-go's and rail0-ts's, so every SDK puts the same text in front of the
+      # user for the same handshake.
+      LOGIN_STATEMENT = "Sign in to RAIL0"
+
+      # The SIWE statement for proving ownership of a wallet being registered —
+      # POST /accounts/:id/wallets.
+      #
+      # A SEPARATE statement, and the separation is the security property rather
+      # than cosmetic: the gateway binds each endpoint to exactly one of these
+      # (Policy::SIWE_LOGIN_STATEMENT / SIWE_WALLET_LINK_STATEMENT) and refuses the
+      # other with 422 siwe_purpose_mismatch. A login signature is handed out on
+      # every sign-in, so a wallet-link endpoint that also accepted one would let
+      # anyone holding a captured login proof bind that address to their OWN
+      # account. Never collapse the two into a single constant.
+      WALLET_LINK_STATEMENT = "Add this wallet to your RAIL0 account"
+
+      attr_reader :http
+
+      def initialize(http)
+        @http = http
+        freeze
+      end
+
+      # Fetch a single-use SIWE nonce from the API (POST /auth/nonces).
+      # @return [Hash] { nonce:, expires_at: }
+      def nonce
+        http.post("/auth/nonces", {})
+      end
+
+      # Submit a pre-built SIWE message and its signature, returning a JWT.
+      # @param message   [String] EIP-4361 formatted message string.
+      # @param signature [String] 0x-prefixed hex signature.
+      # @return [Hash] { token:, address:, account_id:, name:, expires_at: }
+      def verify(message:, signature:)
+        http.post("/auth", { message: message, signature: signature })
+      end
+
+      # End the session whose token this client carries.
+      #
+      # Per TOKEN, not per address: signing out one process leaves the others signed in.
+      # Requires the session it revokes, so the client must be holding one — a client
+      # built without a token gets a 401 rather than a silent no-op.
+      #
+      # `revoked` is the OUTCOME, not a formality, and the reason this returns the body
+      # instead of nil. The gateway's denylist fails open by design — a store outage must
+      # not sign out the whole platform — so `false` means the token is STILL USABLE until
+      # its own expiry, and a caller should treat its copy as compromised rather than
+      # assume the session is gone. rail0-go and rail0-ts have had this; Ruby was the one
+      # SDK where a long-lived process could not hand a session back. (#19)
+      #
+      # @return [Hash] { revoked: true|false }
+      def logout
+        http.post("/auth/logout", {})
+      end
+
+      # End EVERY session of the calling address (POST /auth/revoke_all).
+      #
+      # The answer to a key you no longer trust, and {#logout} cannot be that answer: it
+      # is per TOKEN, so an address with five live sessions needs five tokens the caller
+      # does not have. This is per ADDRESS and reaches the ones it never saw — including
+      # any an attacker is holding.
+      #
+      # The gateway records a cutoff INSTANT rather than enumerating tokens, so a session
+      # minted a moment before the call is refused by its own `iat`. That is what makes it
+      # durable where a denylist is not: there is nothing to enumerate and nothing to miss.
+      #
+      # `cutoff` is the field worth logging. It says exactly which sessions died, which
+      # `revoked: true` cannot.
+      #
+      # @return [Hash] { revoked: true|false, cutoff: "2026-08-27T21:00:00Z" }
+      def revoke_all
+        http.post("/auth/revoke_all", {})
+      end
+
+      # Perform the full SIWE authentication flow:
+      #   1. Fetch a nonce
+      #   2. Build an EIP-4361 message via siwe-rb
+      #   3. Sign it with personal_sign (EIP-191)
+      #   4. Verify with the API and return a JWT
+      #
+      # Requires the optional 'eth' and 'siwe-rb' gems.
+      #
+      # @param private_key [String] 0x-prefixed hex private key of the account wallet.
+      # @param domain      [String] Host of the API server (e.g. "api.rail0.xyz").
+      # @param chain_id    [Integer] Chain ID to embed in the SIWE message. Must match
+      #   the gateway's SIWE_CHAIN_ID policy (default 1); override only when the
+      #   gateway is configured with a different login chain.
+      # @return [Hash] { token:, address:, account_id:, name:, expires_at: }
+      def login(private_key:, domain:, chain_id: 1)
+        message, signature = sign_proof(private_key, domain, chain_id, LOGIN_STATEMENT)
+        verify(message: message, signature: signature)
+      end
+
+      # SIWE proof-of-ownership of the address controlled by +private_key+, to hand
+      # to Wallets#create as its +message+ and +signature+.
+      #
+      # The same handshake as #login — fetch a single-use nonce, build an EIP-4361
+      # message, sign it with EIP-191 personal_sign — but it stops short of POST
+      # /auth: it does NOT authenticate the client. Registering a wallet proves
+      # control of the ADDED address, while the request itself is authorized by the
+      # caller's existing session, and the two addresses may differ (a merchant may
+      # register several payee wallets under one account).
+      #
+      # +private_key+ must therefore be the key OF the address being added, not the
+      # session key — the gateway rejects a signature that does not recover to the
+      # submitted address with 422.
+      #
+      # Requires the optional 'eth' and 'siwe-rb' gems.
+      #
+      # @param private_key [String] 0x-prefixed hex private key of the address being added.
+      # @param domain      [String] Host of the API server (e.g. "api.rail0.xyz").
+      # @param chain_id    [Integer] Chain ID to embed; same meaning and default as #login.
+      # @return [Hash] { message:, signature: } — pass straight to Wallets#create.
+      def prove_address(private_key:, domain:, chain_id: 1)
+        message, signature = sign_proof(private_key, domain, chain_id, WALLET_LINK_STATEMENT)
+        { message: message, signature: signature }
+      end
+
+      private
+
+      # The shared core of both handshakes. Everything but the STATEMENT is
+      # identical, which is precisely why the statement is a parameter and never a
+      # default — see the note on the two constants.
+      def sign_proof(private_key, domain, chain_id, statement)
+        ensure_signing_deps!
+
+        nonce_resp = nonce
+        key        = build_eth_key(private_key)
+
+        msg = Siwe::Message.new(
+          domain:    domain,
+          address:   key.address.to_s,
+          uri:       "https://#{domain}",
+          chain_id:  chain_id,
+          nonce:     nonce_resp[:nonce] || nonce_resp["nonce"],
+          statement: statement
+        )
+        message_str = msg.prepare_message
+        [message_str, personal_sign(key, message_str)]
+      end
+
+      def ensure_signing_deps!
+        original_verbose = $VERBOSE
+        $VERBOSE = nil
+        require "eth"
+        require "siwe"
+        # rubocop:disable Lint/Void -- referencing these constants IS the point: it forces the
+        # autoloaded parser/message files to load here, while warnings are muted, instead of
+        # at the first login where the gem's own warnings would reach the caller's output.
+        Siwe::Parser
+        Siwe::Message
+        # rubocop:enable Lint/Void
+      rescue LoadError => e
+        raise e,
+              "client.auth.login requires the 'eth' and 'siwe-rb' gems. " \
+              "Add them to your Gemfile: gem 'eth', '~> 0.5'; gem 'siwe-rb', '~> 0.2'"
+      ensure
+        $VERBOSE = original_verbose
+      end
+
+      def build_eth_key(private_key)
+        hex = private_key.start_with?("0x") ? private_key[2..] : private_key
+        Eth::Key.new(priv: hex)
+      end
+
+      def personal_sign(key, message)
+        prefixed  = "\x19Ethereum Signed Message:\n#{message.bytesize}#{message}"
+        digest    = Eth::Util.keccak256(prefixed)
+        sig       = key.sign(digest)
+        sig_bytes = [sig].pack("H*")
+        "0x#{sig_bytes.unpack1('H*')}"
+      end
+    end
+  end
+end

data/lib/rail0/resources/chains.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative "query"
+
+module Rail0
+  module Resources
+    # Public blockchain catalog (GET /blockchains, no auth).
+    class Chains
+      include Query
+
+      attr_reader :http
+
+      def initialize(http)
+        @http = http
+        freeze
+      end
+
+      # List active blockchains supported by RAIL0.
+      # @param network_type [String, nil] Filter by "testnet" or "mainnet".
+      # @param symbol [String, nil] Filter by native symbol (case-insensitive, e.g. "ETH").
+      # @return [Array<Hash>] chain_id, name, native_symbol, network_type, explorer_url,
+      #   required_confirmations, finality_tag (the settlement rule: the tag where the
+      #   chain serves one, the count only where it does not)
+      def list(network_type: nil, symbol: nil)
+        http.get("/blockchains#{build_query(network_type: network_type, symbol: symbol)}")
+      end
+    end
+  end
+end

data/lib/rail0/resources/disputes.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative "query"
+
+module Rail0
+  module Resources
+    # Account-level dispute list (requires JWT). Complements
+    # {Payments#disputes} (one payment's open/close history): this surfaces every
+    # dispute — open AND closed — across the authenticated wallet's payments (as
+    # payer or payee), each with its parent payment embedded. A closed dispute
+    # drops out of the payments `disputed` filter (current-state) but still
+    # appears here.
+    class Disputes
+      include Query
+
+      attr_reader :http
+
+      def initialize(http)
+        @http = http
+        freeze
+      end
+
+      # List the account's disputes.
+      # @param status [String, nil] Filter by "open" or "closed".
+      # @param sort [String, nil] Comma-separated sort fields; prefix with - for desc.
+      # @param page [Integer, nil] Page number (1-based).
+      # @param per_page [Integer, nil] Items per page (max 100).
+      # @return [Hash] { data: Array<Hash>, meta: { page:, per_page:, total: } }
+      def list(status: nil, sort: nil, page: nil, per_page: nil)
+        query = build_query(status: status, sort: sort, page: page, per_page: per_page)
+        http.get_list("/disputes#{query}")
+      end
+    end
+  end
+end

data/lib/rail0/resources/health.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Rail0
+  module Resources
+    # Gateway liveness/readiness check (GET /health, no auth).
+    class Health
+      attr_reader :http
+
+      def initialize(http)
+        @http = http
+        freeze
+      end
+
+      # Report gateway health, including database connectivity. The gateway
+      # returns HTTP 503 (raised as Rail0::ApiError) when the database is
+      # unreachable.
+      # @return [Hash] status, api_version, contract_version, db, active_chains, active_contracts, timestamp
+      def get
+        http.get("/health")
+      end
+    end
+  end
+end

data/lib/rail0/resources/payment_methods.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative "query"
+
+module Rail0
+  module Resources
+    # Public, buyer-facing payment-method discovery (GET /payment_methods, no JWT).
+    #
+    # A payer that only knows the merchant — by account id, or by one of the
+    # merchant's wallet addresses — can list the active wallet/token combinations
+    # the merchant accepts, without holding the merchant's session. This is the
+    # public counterpart to the SIWE-gated {Wallets} resource: it exposes only the
+    # active wallets and their active token holdings, never operational fields.
+    class PaymentMethods
+      include Query
+
+      attr_reader :http
+
+      def initialize(http)
+        @http = http
+        freeze
+      end
+
+      # List a merchant's active payment methods. Provide EXACTLY ONE handle:
+      # +account_id+ returns all the merchant's active wallets; +address+ returns
+      # just that one wallet. Passing both (or neither) is rejected by the gateway
+      # with HTTP 400. An unknown account/address yields an empty array.
+      #
+      # @param account_id [String, nil] Merchant account UUID.
+      # @param address [String, nil] A single merchant wallet address (0x).
+      # @return [Array<Hash>] wallets, each with nested active tokens.
+      def list(account_id: nil, address: nil)
+        http.get("/payment_methods#{build_query(account_id: account_id, address: address)}")
+      end
+    end
+  end
+end