solana-sdp 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e006d934cc75d32a431afa36112f78edb06d66dce75632eb3d5247b8c491d29b
+  data.tar.gz: 3766da4b325de50624bb961f60521e07705eb3b70a9115e5be4681152c6083a7
+SHA512:
+  metadata.gz: e43f33123cccad9386df7844d227861ffa61499d6a873a90629d32273a62e1f7c9b365add4eff823bf504f204e78106d7f3456de4ec823ed8042772912b42e9e
+  data.tar.gz: 245615dd77504bd7a4d5890e9868ad01b0137f5c58d8aba6efd02c5b20dbedb98e64d2fecb36cfd705989bd13481e81767bf7ffbf9db210abf1a022d4f56d319

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Jose Ferrer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,141 @@
+# solana-sdp
+
+Ruby SDK for the [Solana Developer Platform](https://github.com/solana-foundation/solana-developer-platform) (SDP) wallets and payments API.
+
+Plain Ruby, zero runtime dependencies (`Net::HTTP`), typed rescuable errors that mirror SDP's real failure modes, and a retry posture that never re-sends a transfer.
+
+> SDP is pre-mainnet, unaudited, and devnet-oriented — so is this gem. Tested against SDP **v0.28** (see [Version pin](#version-pin) below).
+
+## Install
+
+Add to your Gemfile:
+
+```ruby
+gem "solana-sdp"
+```
+
+Or install directly:
+
+```sh
+gem install solana-sdp
+```
+
+Requires Ruby >= 3.2.
+
+## Quickstart
+
+Point the client at a running SDP instance (local default: `http://127.0.0.1:8787`) with an API key:
+
+```ruby
+require "solana-sdp"
+
+# Reads SDP_API_BASE_URL / SDP_API_KEY from ENV, or pass them explicitly.
+client = Sdp::Client.new(api_key: "sk_...")
+
+# One-time custody setup for the project (provider defaults to SDP's
+# configured custody provider; pass provider: "privy" etc. for managed custody).
+client.initialize_custody
+
+# Create a wallet (requires a managed custody provider — see
+# Sdp::ProviderCapabilityError below for what happens on local custody).
+wallet = client.create_wallet(label: "user-42")
+wallet.id         # => "wal_..."  (SDP's walletId — what the payments API expects)
+wallet.public_key # => "8x3f..."
+
+# Check balances. A missing token row means "unavailable", never zero —
+# SDP swallows RPC failures upstream.
+client.wallet_balances(wallet.id).each do |balance|
+  puts "#{balance.token}: #{balance.ui_amount} (#{balance.usd_value || "no price"})"
+end
+
+# Send a transfer (synchronous sign-and-send; SDP confirms before responding).
+transfer = client.create_transfer(
+  source: wallet.id,
+  destination: "Fg6PaFpoGXkYsidMpWTK6W2BeZ7FEfcYkg476zPFsLnS",
+  amount: "0.05",
+  token: "SOL"
+)
+transfer.status    # => "confirmed"
+transfer.signature # => on-chain signature
+
+# List transfers — returns a lazy enumerator that auto-paginates by
+# following meta.hasMore. Pass page: to pin a single page instead.
+client.list_transfers(wallet: wallet.id, direction: "outbound").each do |t|
+  puts "#{t.created_at} #{t.amount} #{t.token} -> #{t.destination} [#{t.status}]"
+end
+```
+
+Also available: `prepare_transfer` (build but don't sign/send, for non-custodial flows), `get_transfer`, `list_wallets`.
+
+`list_wallets` returns an **Array** (`[Sdp::Wallet, ...]`) today — SDP does not paginate `/v1/wallets` at v0.28, so the result is fetched eagerly. When SDP adds pagination this will become a lazy Enumerator (matching `list_transfers`). Use Enumerable methods (`.find`, `.each`, `.map`) rather than array indexing or `.length` to stay forward-compatible.
+
+## Error taxonomy
+
+Everything raised by this gem subclasses `Sdp::Error`, which carries `#code`, `#http_status`, `#details`, and `#meta` alongside the message. Both `#details` and `#meta` are Hashes with **snake_case symbol keys** — SDP's camelCase JSON is converted to Ruby style throughout (e.g. `error.details[:field_errors]`, not `"fieldErrors"` or `:fieldErrors`). The taxonomy mirrors how SDP actually fails:
+
+| Class | Raised when | Retryable? |
+|---|---|---|
+| `Sdp::ConfigurationError` | At construction: `SDP_API_KEY` missing/blank | No — fix config |
+| `Sdp::BadRequest` | 400 — the request itself is wrong (validation errors) | No |
+| `Sdp::ProviderCapabilityError` (< `BadRequest`) | The configured custody provider cannot serve the request: 400 wallet-provisioning gate, or 409 on a second `initialize_custody` | No — change provider config |
+| `Sdp::Unauthorized` | 401 — key missing, malformed, or revoked | No |
+| `Sdp::Forbidden` | 403 | No |
+| `Sdp::InsufficientPermissions` (< `Forbidden`) | 403 with `INSUFFICIENT_PERMISSIONS` — key lacks the required scope | No |
+| `Sdp::NotFound` | 404 — but see the [wallet-scoped key note](#the-wallet-scoped-404) | No |
+| `Sdp::Conflict` | 409 — resource already exists / conflicting state | No |
+| `Sdp::SigningPending` | HTTP 202 — accepted, awaiting additional signatures (multisig/approval flows). **Not a success** | No — poll/approve |
+| `Sdp::TransactionFailed` | `TRANSACTION_FAILED` — the on-chain transaction was attempted and failed (e.g. insufficient lamports) | **Never** — outcome semantics, not transport |
+| `Sdp::RateLimited` | 429 | Yes, with backoff |
+| `Sdp::Timeout` | Read timeout — for POSTs the outcome is **unknown** | Reads yes; writes: reconcile first |
+| `Sdp::Unavailable` | Connection refused/reset, connect timeout, or a 5xx that isn't a recognized capability gate | Yes — the request wasn't processed |
+| `Sdp::TransferExecutionError` (< `Sdp::Error`) | 502 `SOLANA_RPC_ERROR` carrying SDP's NativeAdapter signature — the fee-payment provider cannot submit transactions. **Not caught by `rescue Sdp::Unavailable`** — it is not a transient error | No — configuration fix |
+
+Two of these encode SDP capability gates that otherwise surface as cryptic generic errors (discriminator strings verified against SDP v0.28, documented in `lib/sdp/errors.rb`):
+
+- **`Sdp::ProviderCapabilityError`** — with local custody, SDP holds a single root wallet and `POST /v1/wallets` is rejected ("Wallet provisioning not supported for provider: local"). Wallet-per-User requires a managed provider (e.g. privy): pass `provider:` to `create_wallet` or set `SDP_CUSTODY_PROVIDER`. Also raised when `initialize_custody` is called twice for the same org+project (409) — initialization is one-time.
+- **`Sdp::TransferExecutionError`** — with `FEE_PAYMENT_PROVIDER=native`, SDP can build and sign transfers but cannot submit them; the 502 message contains the `NativeAdapter` signature. Fix: run Kora and set `FEE_PAYMENT_PROVIDER=kora`. A 502 that does *not* match this signature stays `Sdp::Unavailable` — a real RPC outage is never mislabeled as a configuration problem.
+
+## Retry posture
+
+- **GETs retry exactly once** on `Sdp::Timeout` / `Sdp::Unavailable` (transport-level failures), then raise.
+- **POSTs never retry.** SDP has no idempotency key at v0.28: re-sending a transfer after a read timeout risks a double-spend, because the first attempt may have landed on-chain. On `Sdp::Timeout` from a write, reconcile first (e.g. `list_transfers` filtered by wallet, or match a memo) before re-submitting.
+- `Sdp::TransactionFailed` is never retried blindly — it reports an on-chain outcome, not a transport failure.
+- `Sdp::Unavailable` means the request was not processed (connection never opened, or a 5xx without SDP's error envelope), so it is safe to retry — with backoff for `Sdp::RateLimited`.
+
+### The wallet-scoped 404
+
+Wallet-scoped API keys return **404 (not 403)** for wallets outside their scope. "Not found" can therefore mean "not yours". Every `Sdp::NotFound` message carries this hint so the failure is diagnosable from logs.
+
+## Version pin
+
+```ruby
+Sdp::COMPATIBLE_SDP_VERSION # => "0.28"
+```
+
+SDP breaks its API between minor versions. Every release of this gem names the SDP version it was tested against, both here and in the `Sdp::COMPATIBLE_SDP_VERSION` constant. The covered API surface is pinned to a vendored copy of SDP's OpenAPI spec (`spec/openapi-v0.28.json`); contract tests assert every field this gem reads exists in that spec, and `rake "sdp:drift[path/to/newer/openapi.json]"` diffs a newer SDP spec against the pin to report exactly which covered endpoints changed. On an SDP version bump: re-vendor the spec, re-run the contract tests, update `COMPATIBLE_SDP_VERSION`.
+
+Running against a different SDP version may work, but field shapes (e.g. `usdValue` on balances) are known to change between minors.
+
+## Scope
+
+This gem covers SDP's wallets and payments surface: custody initialization, wallet provisioning and listing, balances, and transfers (create/prepare/list/get). Ramps, issuance, and the dashboard APIs are out of scope.
+
+A Rails engine builds on this client — Wallet-per-User provisioning, transfer persistence, and realtime balance updates — as [solrengine-sdp](https://github.com/solrengine/sdp).
+
+## See also
+
+- [solrengine-sdp](https://github.com/solrengine/sdp) — the Rails engine on top of this client: Wallet-per-User provisioning, tracked transfers, live balance updates.
+- [solrengine.org](https://solrengine.org) — the SolRengine family: the connect-your-wallet stack, and how both custody models compose.
+- [Solana Developer Platform](https://github.com/solana-foundation/solana-developer-platform) — the SDP itself: the wallets + payments API this gem covers.
+
+## Development
+
+```sh
+bundle install
+bundle exec rake test     # minitest + WebMock, no network
+bundle exec rubocop
+```
+
+## License
+
+MIT. See [LICENSE.txt](LICENSE.txt).

data/lib/sdp/client.rb

@@ -0,0 +1,293 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "openssl"
+require "json"
+require "uri"
+
+require_relative "errors"
+require_relative "pagination"
+require_relative "resources/wallets"
+require_relative "resources/payments"
+
+module Sdp
+  # Zero-dependency Net::HTTP request core for the SDP API.
+  #
+  # Success envelope:  { "data": ..., "meta": ... }
+  # Error envelope:    { "error": { "code", "message", "details" }, "meta": ... }
+  #
+  # Retry policy: GETs retry once on Timeout/Unavailable. POSTs NEVER retry —
+  # SDP has no idempotency key, so re-sending a transfer risks a double-spend.
+  #
+  # Endpoint methods live in resource modules layered on top of the #get/#post
+  # primitives below; this class owns auth, envelope handling, the typed error
+  # mapping, and the retry posture.
+  class Client
+    include Resources::Wallets
+    include Resources::Payments
+
+    DEFAULT_BASE_URL = "http://127.0.0.1:8787"
+    OPEN_TIMEOUT = 2  # seconds — fail fast when the stack isn't up
+    READ_TIMEOUT = 10 # seconds — transfer confirmation is synchronous
+
+    # Wallet-scoped API keys return 404 (not 403) for wallets outside their
+    # scope, which reads like "does not exist" when it really means "not
+    # yours". Appended to every NotFound so the failure is diagnosable.
+    NOT_FOUND_HINT = "(hint: wallet-scoped API keys return 404 for wallets outside their scope)"
+
+    # Request-layer result: the unwrapped envelope `data` plus `meta`.
+    # Resource methods generally return data to callers; pagination needs
+    # meta (hasMore/page), so the request layer always carries both.
+    Response = Struct.new(:data, :meta, keyword_init: true)
+
+    attr_reader :base_url
+
+    def initialize(base_url: ENV.fetch("SDP_API_BASE_URL", DEFAULT_BASE_URL),
+                   api_key: ENV["SDP_API_KEY"],
+                   open_timeout: OPEN_TIMEOUT,
+                   read_timeout: READ_TIMEOUT)
+      # Strip first, then guard: an ENV key with a trailing newline passes a
+      # naive blank-check but then makes every request raise a raw ArgumentError
+      # from the "Bearer …\n" header. Normalize once, at the boundary.
+      @api_key = api_key.to_s.strip
+      if @api_key.empty?
+        raise ConfigurationError, "SDP_API_KEY is missing or blank. " \
+          "Pass api_key: or set the SDP_API_KEY environment variable."
+      end
+
+      @base_url = base_url.to_s.chomp("/")
+      # base_url is documented as ConfigurationError-covered, so validate it at
+      # boot (mirroring the api_key fail-fast) instead of letting an unusable
+      # URL surface as a cryptic transport error on the first request.
+      parsed = begin
+        URI.parse(@base_url)
+      rescue URI::InvalidURIError
+        nil
+      end
+      unless parsed.is_a?(URI::HTTP) && !parsed.host.to_s.empty?
+        raise ConfigurationError, "SDP_API_BASE_URL is invalid: expected an http(s) URL with a " \
+          "host, got #{@base_url.inspect}. Pass base_url: or set the SDP_API_BASE_URL environment variable."
+      end
+
+      @open_timeout = open_timeout
+      @read_timeout = read_timeout
+    end
+
+    # Redacted on purpose: the API key is a bearer secret and must never leak
+    # into consoles, logs, or exception-capture payloads via the default
+    # #inspect (which would dump every instance variable, @api_key included).
+    def inspect
+      "#<#{self.class} base_url=#{@base_url.inspect}>"
+    end
+
+    # Request primitives — the internal API the resource modules build on.
+    # Both return a Response(data:, meta:) with recursively snake_cased
+    # symbol keys, or raise a typed Sdp::Error.
+
+    # Reads are safe to retry exactly once on transport-level failures.
+    def get(path, query: nil)
+      uri = build_uri(path, query)
+      with_read_retry do
+        perform(Net::HTTP::Get.new(uri), uri, idempotent: true)
+      end
+    end
+
+    def post(path, payload = nil)
+      uri = build_uri(path, nil)
+      request = Net::HTTP::Post.new(uri)
+      request["Content-Type"] = "application/json"
+      request.body = JSON.generate(payload) unless payload.nil?
+      perform(request, uri, idempotent: false) # no retry wrapper — writes are never retried
+    end
+
+    private
+
+    def with_read_retry
+      attempts = 0
+      begin
+        attempts += 1
+        yield
+      rescue Sdp::Timeout, Sdp::Unavailable
+        retry if attempts < 2
+        raise
+      end
+    end
+
+    # idempotent: is the safety hinge. A GET can be re-sent freely, so any
+    # transport failure on it is "unreachable" (Unavailable, retryable). A POST
+    # has no upstream idempotency key, so once the socket was live we cannot
+    # know whether the transfer was processed — those failures must surface as
+    # the unknown-outcome Timeout (reconcile before re-sending), never as a
+    # retryable Unavailable that would risk a double-spend.
+    def perform(request, uri, idempotent:)
+      request["Authorization"] = "Bearer #{@api_key}"
+      request["Accept"] = "application/json"
+
+      response = Net::HTTP.start(
+        uri.host, uri.port,
+        use_ssl: uri.scheme == "https",
+        open_timeout: @open_timeout,
+        read_timeout: @read_timeout
+      ) { |http| http.request(request) }
+
+      handle(response, uri.path)
+    rescue Net::OpenTimeout => e
+      # The TCP connection never opened — the request was definitely not
+      # sent, so this is "unreachable" (safe to retry/fall back), never the
+      # unknown-outcome Timeout that triggers transfer reconciliation. Holds
+      # for POSTs too: nothing crossed the wire.
+      raise Sdp::Unavailable.new("SDP unreachable (connect timeout): #{e.message}", http_status: nil)
+    rescue Net::ReadTimeout => e
+      # The request was fully sent and we timed out awaiting the response —
+      # the outcome is unknown for everyone, so always Timeout.
+      raise Sdp::Timeout.new("SDP request timed out: #{e.message}", http_status: nil)
+    rescue Errno::ECONNREFUSED, Errno::EHOSTUNREACH, SocketError,
+           OpenSSL::SSL::SSLError, Errno::ETIMEDOUT => e
+      # Connection never established / DNS failure / TLS handshake failure /
+      # connect-phase timeout — all provably pre-send, so the request was not
+      # processed. Safe to retry regardless of method.
+      raise Sdp::Unavailable.new("SDP unreachable: #{e.message}", http_status: nil)
+    rescue Errno::ECONNRESET, EOFError, Errno::EPIPE, Net::WriteTimeout => e
+      # The socket was live (reset/EOF/broken-pipe/write-timeout). For a GET
+      # this is still safe to retry. For a POST the reset can land AFTER the
+      # body was delivered and processed — outcome unknown — so it must map to
+      # Timeout (reconcile), not the retryable Unavailable.
+      if idempotent
+        raise Sdp::Unavailable.new("SDP unreachable: #{e.message}", http_status: nil)
+      else
+        raise Sdp::Timeout.new("SDP write failed mid-flight, outcome unknown: #{e.message}", http_status: nil)
+      end
+    end
+
+    def build_uri(path, query)
+      uri = URI.parse("#{@base_url}#{path}")
+      if query
+        compacted = query.compact
+        uri.query = URI.encode_www_form(compacted) unless compacted.empty?
+      end
+      uri
+    end
+
+    def handle(response, path)
+      status = response.code.to_i
+      body = parse_body(response.body)
+
+      # HTTP 202 is SDP's "accepted, awaiting signatures" response. It is in
+      # the 2xx range but carries the ERROR envelope, so it must be handled
+      # before the success branch or it silently parses as a success.
+      raise_typed_error(status, body, path) if status == 202
+
+      if (200..299).cover?(status)
+        # parse_body returns nil both for an empty body (204, fine) and for a
+        # non-empty body that failed to parse. The latter must not slip through
+        # as Response(data: nil) — that NoMethodErrors later in resource
+        # readers. Distinguish the two by the raw body and raise a typed error
+        # for the truncated/unparseable case.
+        if body.nil? && !response.body.to_s.empty?
+          raise Sdp::Unavailable.new("malformed response from SDP (unparseable body)", http_status: status)
+        end
+
+        data = body.is_a?(Hash) && body.key?("data") ? body["data"] : body
+        meta = body.is_a?(Hash) ? body["meta"] : nil
+        return Response.new(data: symbolize(data), meta: symbolize(meta))
+      end
+
+      raise_typed_error(status, body, path)
+    end
+
+    def parse_body(raw)
+      return nil if raw.nil? || raw.empty?
+      JSON.parse(raw)
+    rescue JSON::ParserError
+      nil
+    end
+
+    def raise_typed_error(status, body, path)
+      error = body.is_a?(Hash) ? body["error"] : nil
+      code = error.is_a?(Hash) ? error["code"] : nil
+      message = (error.is_a?(Hash) && error["message"]) || "SDP request failed (HTTP #{status})"
+      details =
+        if error.is_a?(Hash)
+          symbolize(error["details"])
+        elsif body.is_a?(Hash) && body.key?("data")
+          # A 202 (or similar) can carry a data envelope rather than an error
+          # object (e.g. a pending transfer's id). Surface that as details so
+          # the rescued SigningPending can recover the transferId.
+          symbolize(body["data"])
+        end
+      meta = body.is_a?(Hash) ? symbolize(body["meta"]) : nil
+
+      klass = error_class_for(status, code)
+      klass, message = capability_gate(klass, status, code, message, path)
+      message = "#{message} #{NOT_FOUND_HINT}" if klass <= Sdp::NotFound
+      raise klass.new(message, code: code, http_status: status, details: details, meta: meta)
+    end
+
+    # FL-10/FL-11: SDP reports custody/fee-payment capability gates as
+    # generic 400/409/502 responses. Discriminators verified against SDP
+    # v0.28 (pattern constants documented in errors.rb). The upstream
+    # message is preserved and the fix is appended, so logs keep the
+    # original evidence.
+    def capability_gate(klass, status, code, message, path)
+      if status == 400 && path.to_s.end_with?("/v1/wallets") &&
+         message.to_s.match?(Sdp::ProviderCapabilityError::PROVISIONING_GATE_PATTERN)
+        [ Sdp::ProviderCapabilityError,
+          "#{message} — local custody holds a single root wallet; Wallet-per-User requires a " \
+          "managed provider (e.g. privy) — set provider: on create_wallet or SDP_CUSTODY_PROVIDER." ]
+      elsif status == 409 && path.to_s.end_with?("/v1/wallets/initialize")
+        [ Sdp::ProviderCapabilityError,
+          "#{message} — custody is already initialized for this organization/project; " \
+          "initialize_custody is one-time. Use list_wallets to find the existing root wallet." ]
+      elsif status == 502 && code == "SOLANA_RPC_ERROR" &&
+            message.to_s.match?(Sdp::TransferExecutionError::NATIVE_ADAPTER_PATTERN)
+        [ Sdp::TransferExecutionError,
+          "#{message} — SDP's native fee adapter cannot submit transactions; " \
+          "run Kora and set FEE_PAYMENT_PROVIDER=kora." ]
+      else
+        [ klass, message ]
+      end
+    end
+
+    # Code takes precedence over status; status is the fallback. A 5xx that
+    # doesn't carry SDP's error shape is treated as Unavailable (proxy error,
+    # crash page, etc.) so GETs can retry it.
+    def error_class_for(status, code)
+      case code
+      when "UNAUTHORIZED"               then return Sdp::Unauthorized
+      when "INSUFFICIENT_PERMISSIONS"   then return Sdp::InsufficientPermissions
+      when "FORBIDDEN"                  then return Sdp::Forbidden
+      when "TRANSACTION_FAILED"         then return Sdp::TransactionFailed
+      when "RATE_LIMITED"               then return Sdp::RateLimited
+      when "NOT_FOUND"                  then return Sdp::NotFound
+      when "CONFLICT"                   then return Sdp::Conflict
+      when "SIGNING_PENDING"            then return Sdp::SigningPending
+      when "BAD_REQUEST", "VALIDATION_ERROR" then return Sdp::BadRequest
+      end
+
+      case status
+      when 202 then Sdp::SigningPending
+      when 401 then Sdp::Unauthorized
+      when 403 then Sdp::Forbidden
+      when 404 then Sdp::NotFound
+      when 409 then Sdp::Conflict
+      when 429 then Sdp::RateLimited
+      when 400..499 then Sdp::BadRequest
+      when 500..599 then Sdp::Unavailable
+      else Sdp::Error
+      end
+    end
+
+    # camelCase JSON → snake_case symbol keys, recursively.
+    def symbolize(value)
+      case value
+      when Hash  then value.each_with_object({}) { |(k, v), h| h[underscore_key(k)] = symbolize(v) }
+      when Array then value.map { |v| symbolize(v) }
+      else value
+      end
+    end
+
+    def underscore_key(key)
+      key.to_s.gsub(/([a-z\d])([A-Z])/, '\1_\2').downcase.to_sym
+    end
+  end
+end

data/lib/sdp/coverage.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Sdp
+  # The curated SDP surface this gem covers, pinned against the vendored
+  # OpenAPI spec (spec/openapi-v0.28.json). Consumed by the contract tests
+  # (test/sdp/contract_test.rb) and the sdp:drift rake task.
+  #
+  # Path templates use the {param} style of SDP's generated spec. When a
+  # resource method is added or removed, this map changes in the same commit.
+  module Coverage
+    # method/path identify the operation; success_status is the documented
+    # success response; reads maps a navigation path inside the success
+    # schema to the camelCase fields our structs read at that node. A "[]"
+    # segment descends into array items; the empty path is the schema root.
+    Endpoint = Struct.new(:method, :path, :success_status, :reads, keyword_init: true)
+
+    # Fields read by Sdp::Wallet.from_hash.
+    WALLET_FIELDS = %w[id walletId publicKey label status provider purpose createdAt balances].freeze
+    # Fields read by Sdp::Balance.from_hash. usdValue is optional upstream —
+    # presence in the schema's properties is what we pin, not requiredness.
+    BALANCE_FIELDS = %w[token mint amount uiAmount decimals usdValue].freeze
+    # Fields read by Sdp::Transfer.from_hash.
+    TRANSFER_FIELDS = %w[id direction status signature token amount source destination memo error createdAt].freeze
+
+    COVERED_ENDPOINTS = [
+      # NOTE: at v0.28 the initialize 201 response has NO data envelope —
+      # configId/publicKey/walletId sit at the schema root.
+      Endpoint.new(method: "post", path: "/v1/wallets/initialize", success_status: "201",
+                   reads: { [] => %w[configId publicKey walletId] }),
+      Endpoint.new(method: "post", path: "/v1/wallets", success_status: "201",
+                   reads: { %w[data wallet] => WALLET_FIELDS }),
+      Endpoint.new(method: "get", path: "/v1/wallets", success_status: "200",
+                   reads: { [ "data", "wallets", "[]" ] => WALLET_FIELDS }),
+      Endpoint.new(method: "get", path: "/v1/payments/wallets/{walletId}/balances", success_status: "200",
+                   reads: { %w[data walletBalances] => %w[walletId balances],
+                            [ "data", "walletBalances", "balances", "[]" ] => BALANCE_FIELDS }),
+      Endpoint.new(method: "post", path: "/v1/payments/transfers", success_status: "200",
+                   reads: { %w[data transfer] => TRANSFER_FIELDS }),
+      Endpoint.new(method: "post", path: "/v1/payments/transfers/prepare", success_status: "200",
+                   reads: { %w[data] => %w[transfer preparedTransaction simulation],
+                            %w[data transfer] => TRANSFER_FIELDS,
+                            %w[data preparedTransaction] => %w[serialized blockhash lastValidBlockHeight] }),
+      Endpoint.new(method: "get", path: "/v1/payments/transfers", success_status: "200",
+                   reads: { [ "data", "[]" ] => TRANSFER_FIELDS }),
+      Endpoint.new(method: "get", path: "/v1/payments/transfers/{transferId}", success_status: "200",
+                   reads: { %w[data transfer] => TRANSFER_FIELDS })
+    ].freeze
+
+    class << self
+      # The application/json schema of the endpoint's documented success
+      # response, $ref-resolved. nil when the spec doesn't document it.
+      def success_schema(spec, endpoint)
+        operation = spec.dig("paths", endpoint.path, endpoint.method)
+        schema = operation&.dig("responses", endpoint.success_status, "content", "application/json", "schema")
+        resolve(spec, schema)
+      end
+
+      # Navigates a (resolved) schema along a reads path. "[]" descends into
+      # array items; any other segment descends into that property. Returns
+      # the resolved node, or nil as soon as the path breaks.
+      def walk(spec, schema, segments)
+        segments.reduce(resolve(spec, schema)) do |node, segment|
+          break nil unless node
+
+          child = segment == "[]" ? node["items"] : node.dig("properties", segment)
+          resolve(spec, child)
+        end
+      end
+
+      # Follows "$ref": "#/components/schemas/X" pointers (recursively, with
+      # a depth guard). SDP's generated spec is fully inlined today (zero
+      # $refs at v0.28) — this keeps the guard working if that changes.
+      def resolve(spec, node, depth = 0)
+        return node unless node.is_a?(Hash) && node["$ref"].is_a?(String)
+        return nil if depth > 10
+
+        name = node["$ref"][%r{\A#/components/schemas/(.+)\z}, 1]
+        return nil unless name
+
+        resolve(spec, spec.dig("components", "schemas", name), depth + 1)
+      end
+    end
+  end
+end

data/lib/sdp/drift.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "coverage"
+
+module Sdp
+  # Diffs a newer SDP OpenAPI spec against the vendored pin, restricted to
+  # the covered surface (Sdp::Coverage::COVERED_ENDPOINTS). Drives the
+  # `rake "sdp:drift[path]"` task.
+  #
+  # A diff is a REPORT, not a build failure: SDP moving must never break this
+  # gem's own CI, so #run always returns normally (the rake task exits 0).
+  # The one hard rule: an unreadable spec prints "drift check unavailable"
+  # and never a false "no drift" claim.
+  module Drift
+    module_function
+
+    # Prints a drift report to `out`. Returns the findings array, or nil when
+    # the check could not run at all.
+    def run(pinned_path:, newer_path:, out: $stdout)
+      newer = read_spec(newer_path)
+      if newer.nil?
+        out.puts "drift check unavailable: could not read newer spec at #{newer_path.inspect}"
+        return nil
+      end
+
+      pinned = read_spec(pinned_path)
+      if pinned.nil?
+        out.puts "drift check unavailable: could not read pinned spec at #{pinned_path.inspect}"
+        return nil
+      end
+
+      findings = diff(pinned, newer)
+      if findings.empty?
+        out.puts "No drift on the covered surface (#{Coverage::COVERED_ENDPOINTS.size} endpoints)."
+      else
+        out.puts "Drift detected on the covered surface (#{findings.size} finding(s) — report, not a failure):"
+        findings.each { |finding| out.puts "  - #{finding}" }
+      end
+      findings
+    end
+
+    # Compares the two parsed specs over the covered endpoints only.
+    # Returns human-readable finding strings; uncovered endpoints (ramps,
+    # issuance, ...) never appear here no matter how much they change.
+    def diff(pinned, newer)
+      Coverage::COVERED_ENDPOINTS.flat_map do |endpoint|
+        label = "#{endpoint.method.upcase} #{endpoint.path}"
+        newer_operation = newer.dig("paths", endpoint.path, endpoint.method)
+        next [ "#{label}: endpoint missing from newer spec" ] unless newer_operation
+
+        response_findings(label, endpoint, pinned, newer) +
+          request_findings(label, endpoint, pinned, newer)
+      end
+    end
+
+    def read_spec(path)
+      JSON.parse(File.read(path.to_s))
+    rescue StandardError
+      nil
+    end
+
+    # For every schema node the gem reads, reports fields that disappeared
+    # (removed/renamed) and fields that became required (shape guarantees
+    # changed — e.g. the v0.28→v0.29 usdValue change on balances).
+    def response_findings(label, endpoint, pinned, newer)
+      pinned_schema = Coverage.success_schema(pinned, endpoint)
+      newer_schema = Coverage.success_schema(newer, endpoint)
+      return [ "#{label}: success response #{endpoint.success_status} missing from newer spec" ] unless newer_schema
+      return [] unless pinned_schema # nothing pinned to compare against
+
+      endpoint.reads.flat_map do |segments, _fields|
+        at = segments.empty? ? "response root" : "response #{segments.join('.')}"
+        pinned_node = Coverage.walk(pinned, pinned_schema, segments)
+        newer_node = Coverage.walk(newer, newer_schema, segments)
+        next [] unless pinned_node
+        next [ "#{label}: #{at} no longer present in newer spec" ] unless newer_node
+
+        findings = []
+        removed = properties(pinned_node) - properties(newer_node)
+        findings << "#{label}: #{at} removed/renamed field(s): #{removed.join(', ')}" unless removed.empty?
+
+        newly_required = required(newer_node) - required(pinned_node)
+        unless newly_required.empty?
+          findings << "#{label}: #{at} field(s) became required: #{newly_required.join(', ')}"
+        end
+        findings
+      end
+    end
+
+    # Reports request-body params that became required in the newer spec —
+    # existing gem calls would start failing with 400s.
+    def request_findings(label, endpoint, pinned, newer)
+      pinned_required = request_required(pinned, endpoint)
+      newer_required = request_required(newer, endpoint)
+
+      added = newer_required - pinned_required
+      return [] if added.empty?
+
+      [ "#{label}: request body added required param(s): #{added.join(', ')}" ]
+    end
+
+    def request_required(spec, endpoint)
+      schema = spec.dig("paths", endpoint.path, endpoint.method,
+                        "requestBody", "content", "application/json", "schema")
+      required(Coverage.resolve(spec, schema))
+    end
+
+    def properties(node)
+      props = node.is_a?(Hash) ? node["properties"] : nil
+      props.is_a?(Hash) ? props.keys : []
+    end
+
+    def required(node)
+      req = node.is_a?(Hash) ? node["required"] : nil
+      req.is_a?(Array) ? req : []
+    end
+  end
+end

data/lib/sdp/errors.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module Sdp
+  # Base class for every error raised by Sdp::Client.
+  #
+  # SDP's uniform error shape is:
+  #   { "error": { "code": "...", "message": "...", "details": ... }, "meta": { ... } }
+  #
+  # The upstream message is preserved as the exception message; the upstream
+  # code, HTTP status, details, and meta ride along for logging/branching.
+  class Error < StandardError
+    attr_reader :code, :http_status, :details, :meta
+
+    def initialize(message = nil, code: nil, http_status: nil, details: nil, meta: nil)
+      super(message)
+      @code = code
+      @http_status = http_status
+      @details = details
+      @meta = meta
+    end
+  end
+
+  # Raised at construction/boot when SDP_API_KEY (or base URL) is unusable.
+  class ConfigurationError < Error; end
+
+  # 400 / BAD_REQUEST / VALIDATION_ERROR — the request itself is wrong.
+  class BadRequest < Error; end
+
+  # A request the configured custody provider cannot serve — not a malformed
+  # request. Raised for the FL-10 gates:
+  #
+  # - 400 whose message matches PROVISIONING_GATE_PATTERN: local custody
+  #   holds exactly one root wallet, so POST /v1/wallets is rejected.
+  #   Wallet-per-User requires a managed provider (e.g. privy).
+  # - 409 on POST /v1/wallets/initialize: custody is already initialized for
+  #   this organization/project — initialization is one-time.
+  #
+  # Subclasses BadRequest so existing rescues keep working; never retryable —
+  # the same request fails until the provider configuration changes.
+  class ProviderCapabilityError < BadRequest
+    # Verified against SDP v0.28: assertCustodyProviderCanCreateWallet
+    # (apps/sdp-api/src/services/custody-provider-lifecycle.service.ts) and
+    # createProviderWallet (services/domain/signing/provider-wallet-lifecycle.ts)
+    # both throw:
+    #   "Wallet provisioning not supported for provider: ${provider}"
+    PROVISIONING_GATE_PATTERN = /Wallet provisioning not supported/i
+  end
+
+  # 502 / SOLANA_RPC_ERROR carrying the NativeAdapter signature — the FL-11
+  # gate. With FEE_PAYMENT_PROVIDER=native, SDP can build and sign transfers
+  # but cannot SUBMIT them; the fix is configuration (run Kora, set
+  # FEE_PAYMENT_PROVIDER=kora), so retrying is pointless. A 502 that does
+  # NOT match the pattern is a real upstream outage and stays Unavailable —
+  # mislabeling an RPC outage as "configure Kora" would be worse than a
+  # generic error.
+  class TransferExecutionError < Error
+    # Verified against SDP v0.28: NativeAdapter#signAndSend
+    # (apps/sdp-api/src/services/adapters/fee-payment/native/native.adapter.ts)
+    # throws:
+    #   "NativeAdapter.signAndSend not supported - use KoraAdapter for gasless transactions"
+    # (#signAsFeePayer throws the same shape with its own method name).
+    NATIVE_ADAPTER_PATTERN = /NativeAdapter\.\w+ not supported - use KoraAdapter/
+  end
+
+  # 401 / UNAUTHORIZED — key missing, malformed, or revoked.
+  class Unauthorized < Error; end
+
+  # 403 / FORBIDDEN — authenticated but not allowed.
+  class Forbidden < Error; end
+
+  # 403 / INSUFFICIENT_PERMISSIONS — key lacks the required scope.
+  class InsufficientPermissions < Forbidden; end
+
+  # 404 / NOT_FOUND — wallet or transfer does not exist. Beware: wallet-scoped
+  # API keys return 404 (not 403) for wallets outside their scope.
+  class NotFound < Error; end
+
+  # 409 / CONFLICT — the resource already exists or is in a conflicting state
+  # (e.g. initializing a project wallet twice).
+  class Conflict < Error; end
+
+  # HTTP 202 / SIGNING_PENDING — the request was accepted but the transaction
+  # is awaiting additional signatures (multisig/approval flows). NOT a
+  # success: there is no data envelope, only an error-shaped body. Carries
+  # code/http_status/details so callers can surface approval progress.
+  class SigningPending < Error; end
+
+  # TRANSACTION_FAILED — the on-chain transaction was attempted and failed
+  # (e.g. insufficient lamports). Never blindly retried: outcome semantics
+  # differ from transport errors.
+  class TransactionFailed < Error; end
+
+  # 429 / RATE_LIMITED.
+  class RateLimited < Error; end
+
+  # Net::ReadTimeout. For POSTs the outcome is UNKNOWN — callers must
+  # reconcile before re-submitting (no idempotency key upstream; retrying a
+  # transfer risks a double-spend).
+  class Timeout < Error; end
+
+  # Connection refused/reset, connect timeout, or a 5xx without SDP's error
+  # shape. The request was never processed, so it is safe to retry.
+  class Unavailable < Error; end
+end

data/lib/sdp/pagination.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Sdp
+  # Lazy enumeration over SDP list endpoints.
+  #
+  # Two modes, keyed on whether the caller pinned a page:
+  #
+  # - No :page in the query — auto-paginate. The enumerator fetches the first
+  #   page on first consumption and follows meta.hasMore, requesting the next
+  #   page only when iteration runs past the rows already fetched (so
+  #   `enum.take(3)` against a 20-row first page performs exactly one
+  #   request). Filters are re-sent on every page request.
+  # - Explicit :page — single page. The enumerator yields exactly that page's
+  #   rows and never fetches another, even when meta.hasMore is true.
+  #
+  # :pageSize is clamped client-side to MAX_PAGE_SIZE — SDP rejects larger
+  # values, and a clamped request is more useful than a guaranteed 400.
+  #
+  # Non-paginated list endpoints (GET /v1/wallets at v0.28) flow through the
+  # same helper: their meta carries no hasMore, so enumeration stops after a
+  # single fetch — and they pick up auto-pagination for free if SDP paginates
+  # them in a later version.
+  module Pagination
+    MAX_PAGE_SIZE = 100    # SDP's pageSize ceiling (v0.28)
+    MAX_PAGES     = 10_000 # defensive ceiling; empty-page + hasMore guards are the primary stop
+
+    # client — anything exposing #get(path, query:) → Client::Response
+    # query  — wire-shaped (camelCase keys), nils allowed (compacted here)
+    # mapper — called once per page with the Response; returns that page's rows
+    def self.enumerate(client, path, query = {}, &mapper)
+      query = query.compact
+      query[:pageSize] = [ query[:pageSize].to_i, MAX_PAGE_SIZE ].min if query.key?(:pageSize)
+      single_page = query.key?(:page)
+
+      Enumerator.new do |yielder|
+        page = query[:page]
+        loop do
+          request_query = page ? query.merge(page: page) : query
+          response = client.get(path, query: request_query)
+          rows = mapper.call(response)
+          rows.each { |row| yielder << row }
+
+          break if single_page
+
+          meta = response.meta || {}
+          # An empty page also stops: hasMore with zero rows would loop forever.
+          break if rows.empty? || !meta[:has_more]
+
+          # Advance a LOCAL counter the client owns; ignore meta[:page] so a
+          # server that echoes the wrong page number cannot cause an infinite
+          # loop or a TypeError (string "1" + 1).
+          page = (page || 1) + 1
+          break if page > MAX_PAGES
+        end
+      end
+    end
+  end
+end

data/lib/sdp/resources/payments.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Sdp
+  # A transfer as SDP reports it. SDP omits optional fields entirely —
+  # source/destination/amount/memo can be ABSENT from the JSON, not null —
+  # so every member is nil when SDP didn't send it.
+  Transfer = Struct.new(:id, :direction, :status, :signature, :token, :amount,
+                        :source, :destination, :memo, :error, :created_at,
+                        keyword_init: true) do
+    def self.from_hash(hash)
+      hash ||= {}
+      new(
+        id: hash[:id],
+        direction: hash[:direction],
+        status: hash[:status],
+        signature: hash[:signature],
+        token: hash[:token],
+        amount: hash[:amount],
+        source: hash[:source],
+        destination: hash[:destination],
+        memo: hash[:memo],
+        error: hash[:error],
+        created_at: hash[:created_at]
+      )
+    end
+  end
+
+  # Result of POST /v1/payments/transfers/prepare: the provisional transfer
+  # plus the unsigned transaction the caller must sign and submit before
+  # blockhash expiry. simulation is SDP's simulation result passed through
+  # as a hash when present.
+  PreparedTransfer = Struct.new(:transfer, :serialized, :blockhash, :last_valid_block_height, :simulation,
+                                keyword_init: true) do
+    def self.from_hash(hash)
+      hash ||= {}
+      prepared = hash[:prepared_transaction] || {}
+      new(
+        transfer: Transfer.from_hash(hash[:transfer]),
+        serialized: prepared[:serialized],
+        blockhash: prepared[:blockhash],
+        last_valid_block_height: prepared[:last_valid_block_height],
+        simulation: hash[:simulation]
+      )
+    end
+  end
+
+  module Resources
+    # Payment endpoints: transfer create/prepare/list/get.
+    module Payments
+      # POST /v1/payments/transfers → Sdp::Transfer
+      # Synchronous sign-and-send: SDP confirms before responding, and the
+      # request is NEVER retried (no idempotency key upstream — see Client
+      # docs). amount is serialized as a decimal string; token is "SOL" or
+      # an SPL mint address.
+      def create_transfer(source:, destination:, amount:, token: "SOL", memo: nil)
+        response = post("/v1/payments/transfers", transfer_payload(source, destination, amount, token, memo))
+        data = response.data
+        src = data.is_a?(Hash) ? (data[:transfer] || data) : data
+        Transfer.from_hash(src)
+      end
+
+      # POST /v1/payments/transfers/prepare → Sdp::PreparedTransfer
+      # Builds — but does not sign or send — the transaction, for
+      # non-custodial flows where the caller holds the keys.
+      def prepare_transfer(source:, destination:, amount:, token: "SOL", memo: nil,
+                           reference_address: nil, options: nil)
+        payload = transfer_payload(source, destination, amount, token, memo)
+        payload[:referenceAddress] = reference_address if reference_address
+        payload[:options] = options if options
+        PreparedTransfer.from_hash(post("/v1/payments/transfers/prepare", payload).data)
+      end
+
+      # GET /v1/payments/transfers → Enumerator yielding Sdp::Transfer
+      #
+      # Auto-paginates: without page:, the returned lazy enumerator follows
+      # meta.hasMore across pages, fetching each page only when iteration
+      # reaches it and re-sending the filters every time. With an explicit
+      # page:, it yields exactly that page and never fetches another.
+      # page_size is clamped to Pagination::MAX_PAGE_SIZE (100).
+      #
+      # Filters: wallet: (walletId), wallet_address:, token:, direction:
+      # ("inbound"/"outbound"), status: (string or array, sent
+      # comma-separated), page:, page_size:.
+      def list_transfers(wallet: nil, wallet_address: nil, token: nil, direction: nil,
+                         status: nil, page: nil, page_size: nil)
+        query = {
+          wallet: wallet,
+          walletAddress: wallet_address,
+          token: token,
+          direction: direction,
+          status: status && Array(status).join(","),
+          page: page,
+          pageSize: page_size
+        }.compact
+        Pagination.enumerate(self, "/v1/payments/transfers", query) do |response|
+          rows = response.data.is_a?(Array) ? response.data : []
+          rows.map { |transfer| Transfer.from_hash(transfer) }
+        end
+      end
+
+      # GET /v1/payments/transfers/:id → Sdp::Transfer
+      def get_transfer(transfer_id)
+        response = get("/v1/payments/transfers/#{encode_path_segment(transfer_id)}")
+        data = response.data
+        src = data.is_a?(Hash) ? (data[:transfer] || data) : data
+        Transfer.from_hash(src)
+      end
+
+      private
+
+      def transfer_payload(source, destination, amount, token, memo)
+        payload = { source: source, destination: destination, token: token, amount: amount.to_s }
+        payload[:memo] = memo if memo
+        payload
+      end
+
+      def encode_path_segment(segment)
+        URI.encode_uri_component(segment.to_s)
+      end
+    end
+  end
+end

data/lib/sdp/resources/wallets.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Sdp
+  # Token balance row from GET /v1/payments/wallets/:id/balances.
+  # amount is base units (string); ui_amount is the decimal string.
+  # usd_value is passed through when SDP includes it and is nil otherwise
+  # (varies across SDP versions) — nil means "no price", never zero.
+  Balance = Struct.new(:token, :mint, :amount, :ui_amount, :decimals, :usd_value, keyword_init: true) do
+    def self.from_hash(hash)
+      hash ||= {}
+      new(
+        token: hash[:token],
+        mint: hash[:mint],
+        amount: hash[:amount],
+        ui_amount: hash[:ui_amount],
+        decimals: hash[:decimals],
+        usd_value: hash[:usd_value]
+      )
+    end
+  end
+
+  # Custody wallet. #id is SDP's walletId — the identifier the payments API
+  # expects — not the database row id. balances is only populated when the
+  # list was fetched with include_balances: true.
+  Wallet = Struct.new(:id, :public_key, :label, :status, :provider, :purpose, :created_at, :balances,
+                      keyword_init: true) do
+    def self.from_hash(hash)
+      hash ||= {}
+      new(
+        id: hash[:wallet_id] || hash[:id],
+        public_key: hash[:public_key],
+        label: hash[:label],
+        status: hash[:status],
+        provider: hash[:provider],
+        purpose: hash[:purpose],
+        created_at: hash[:created_at],
+        balances: hash[:balances]&.map { |balance| Balance.from_hash(balance) }
+      )
+    end
+  end
+
+  module Resources
+    # Wallet endpoints: custody initialize, create, list, plus the balances
+    # read (which lives under /v1/payments but is wallet-shaped).
+    module Wallets
+      # POST /v1/wallets/initialize — one-time project custody setup.
+      # Both fields are optional; the request is sent without a body when
+      # neither is given. Returns the snake_cased data hash exactly as SDP
+      # sent it (custody config + root wallet fields incl. :public_key) —
+      # kept tolerant because the shape varies by custody provider.
+      def initialize_custody(provider: nil, wallet_label: nil)
+        payload = { provider: provider, walletLabel: wallet_label }.compact
+        post("/v1/wallets/initialize", payload.empty? ? nil : payload).data
+      end
+
+      # POST /v1/wallets → Sdp::Wallet. Wallet#id is SDP's walletId.
+      def create_wallet(label:, provider: nil)
+        response = post("/v1/wallets", { label: label, provider: provider }.compact)
+        data = response.data
+        src = data.is_a?(Hash) ? (data[:wallet] || data) : data
+        Wallet.from_hash(src)
+      end
+
+      # GET /v1/wallets → [Sdp::Wallet, ...]
+      # Filters (camelCased on the wire): provider:, project_id:,
+      # include_balances:. Not paginated at v0.28 — the whole list comes back
+      # in one response — but routed through Pagination.enumerate so a
+      # paginated upstream upgrade is a one-line change here.
+      def list_wallets(provider: nil, project_id: nil, include_balances: nil)
+        query = { provider: provider, projectId: project_id, includeBalances: include_balances }.compact
+        Pagination.enumerate(self, "/v1/wallets", query) do |response|
+          rows =
+            case response.data
+            when Array then response.data
+            when Hash  then response.data[:wallets] || []
+            else []
+            end
+          rows.map { |wallet| Wallet.from_hash(wallet) }
+        end.to_a
+      end
+
+      # GET /v1/payments/wallets/:id/balances → [Sdp::Balance, ...]
+      # Upstream swallows RPC failures, so a token row (even SOL) may be
+      # MISSING entirely — a missing row means "unavailable", never zero.
+      def wallet_balances(wallet_id)
+        data = get("/v1/payments/wallets/#{encode_path_segment(wallet_id)}/balances").data
+        container = data.is_a?(Hash) ? (data[:wallet_balances] || data) : {}
+        (container[:balances] || []).map { |balance| Balance.from_hash(balance) }
+      end
+
+      private
+
+      def encode_path_segment(segment)
+        URI.encode_uri_component(segment.to_s)
+      end
+    end
+  end
+end

data/lib/sdp/version.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Sdp
+  VERSION = "0.1.0"
+
+  # The SDP release this gem version is tested against. SDP breaks its API
+  # between minors, so every gem release names its verified upstream version.
+  COMPATIBLE_SDP_VERSION = "0.28"
+end

data/lib/sdp.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require_relative "sdp/version"
+require_relative "sdp/errors"
+require_relative "sdp/client"
+require_relative "sdp/coverage"
+
+# Ruby client for the Solana Developer Platform (SDP).
+module Sdp
+end

data/lib/solana-sdp.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+# Entry point matching the gem name: `require "solana-sdp"`.
+require_relative "sdp"

metadata

@@ -0,0 +1,58 @@
+--- !ruby/object:Gem::Specification
+name: solana-sdp
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Jose Ferrer
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-06-13 00:00:00.000000000 Z
+dependencies: []
+description: 'Zero-dependency Net::HTTP client for SDP''s wallets and payments API:
+  typed errors, envelope unwrapping, and a safe retry posture.'
+email:
+- estoy@moviendo.me
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- lib/sdp.rb
+- lib/sdp/client.rb
+- lib/sdp/coverage.rb
+- lib/sdp/drift.rb
+- lib/sdp/errors.rb
+- lib/sdp/pagination.rb
+- lib/sdp/resources/payments.rb
+- lib/sdp/resources/wallets.rb
+- lib/sdp/version.rb
+- lib/solana-sdp.rb
+homepage: https://github.com/solrengine/solana-sdp
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/solrengine/solana-sdp
+  source_code_uri: https://github.com/solrengine/solana-sdp
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Ruby client for the Solana Developer Platform (SDP)
+test_files: []