rail0-sdk 1.0.0

data/lib/rail0/resources/payments.rb

@@ -0,0 +1,344 @@
+# frozen_string_literal: true
+
+require_relative "query"
+
+module Rail0
+  module Resources
+    # Payment lifecycle operations.
+    #
+    # Every on-chain operation is two-phase: a +*_prepare+ call returns an unsigned
+    # EIP-1559 transaction (sign it locally with {Rail0::Signing.sign_transaction}),
+    # then the matching submit call broadcasts the signed raw tx (HTTP 202, async —
+    # poll {get} until the status settles). Wallets that sign and broadcast in one
+    # step (e.g. MetaMask) skip the local signer and report the hash via
+    # {submit_by_hash} instead.
+    class Payments
+      include Query
+
+      # Operations accepted by the prepare/submit endpoints.
+      OPERATIONS = %w[authorize capture charge void release refund].freeze
+
+      attr_reader :http
+
+      def initialize(http)
+        @http = http
+        freeze
+      end
+
+      # List payments for the authenticated wallet (requires JWT). Returns
+      # payments where the caller is the payer or payee.
+      # @param status [String, nil] Filter by payment status.
+      # @param mode [String, nil] Filter by mode ("authorize" or "charge").
+      # @param payer [String, nil] Filter by payer address.
+      # @param payee [String, nil] Filter by payee address.
+      # @param token [String, nil] Filter by token contract address.
+      # @param rail0_id [String, nil] Filter by the logical on-chain payment id (0x…).
+      # @param chain_id [Integer, nil] Filter by the payment's chain.
+      # @param disputed [Boolean, nil] Filter by whether an open dispute exists.
+      # @param min_amount [String, nil] Minimum amount in token BASE UNITS (inclusive).
+      # @param max_amount [String, nil] Maximum amount in token BASE UNITS (inclusive).
+      #   These two really are base units — the filter runs against the stored column.
+      #   Amounts you SEND (create, capture, refund) are human decimals instead, which
+      #   the gateway scales by the token's decimals. The two units coexist in the API.
+      # @param created_from [String, nil] Only payments created at/after this ISO-8601 time.
+      # @param created_to [String, nil] Only payments created at/before this ISO-8601 time.
+      # @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, mode: nil, payer: nil, payee: nil, token: nil, rail0_id: nil,
+               chain_id: nil, disputed: nil, min_amount: nil, max_amount: nil,
+               created_from: nil, created_to: nil, sort: nil, page: nil, per_page: nil)
+        query = build_query(status: status, mode: mode, payer: payer, payee: payee, token: token,
+                            rail0_id: rail0_id, chain_id: chain_id, disputed: disputed,
+                            min_amount: min_amount, max_amount: max_amount,
+                            created_from: created_from, created_to: created_to,
+                            sort: sort, page: page, per_page: per_page)
+        http.get_list("/payments#{query}")
+      end
+
+      # Create a payment. Returns the record — when still unsigned it embeds the
+      # EIP-3009 +signing_payload+ for the payer to sign.
+      #
+      # Pass +idempotency_key+ to make the request replay-safe: a repeated call
+      # with the same key returns the existing payment (HTTP 200) instead of
+      # creating a new one.
+      #
+      # Accepts either a params Hash or keyword fields:
+      #   create(chain_id: 84532, mode: "authorize", amount: "100.00", token: "0x…", payer: "0x…", payee: "0x…")
+      #   create({ chain_id: 84532, ... }, idempotency_key: "order-42")
+      #
+      # @param params [Hash, nil] chain_id, mode, amount, token, payer, payee, description (opt), metadata (opt).
+      # @param idempotency_key [String, nil] Optional Idempotency-Key header value.
+      # @param fields [Hash] Field keywords, used when +params+ is omitted.
+      # @return [Hash]
+      def create(params = nil, idempotency_key: nil, **fields)
+        body    = params || fields
+        headers = idempotency_key ? { "Idempotency-Key" => idempotency_key } : {}
+        http.post("/payments", body, headers: headers)
+      end
+
+      # Fetch current payment state (DB status + live on-chain amounts + transactions).
+      # @param id [String] Payment UUID or rail0_id.
+      # @return [Hash]
+      def get(id)
+        http.get("/payments/#{id}")
+      end
+
+      # List on-chain transactions for a payment.
+      # @param id [String] Payment UUID or rail0_id.
+      # @param operation [String, nil] Filter by operation (see {OPERATIONS}).
+      # @param status [String, nil] Filter by transaction status.
+      # @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 transactions(id, operation: nil, status: nil, sort: nil, page: nil, per_page: nil)
+        query = build_query(operation: operation, status: status, sort: sort, page: page, per_page: per_page)
+        http.get_list("/payments/#{id}/transactions#{query}")
+      end
+
+      # Fetch ONE of a payment's transactions
+      # (GET /payments/{id}/transactions/{transaction_id}).
+      #
+      # The lookup for an action id: anything handed a transaction id when an
+      # operation was accepted resolves it directly, instead of fetching the payment
+      # and scanning its transactions for an id it already holds. Readable by either
+      # participant; an unknown, malformed or foreign id all answer 404 alike.
+      # (rail0-gateway#330)
+      #
+      # @param id [String] Payment UUID or rail0_id.
+      # @param transaction_id [String] Transaction UUID.
+      # @return [Hash]
+      def get_transaction(id, transaction_id)
+        http.get("/payments/#{id}/transactions/#{transaction_id}")
+      end
+
+      # Re-enqueue a stuck broadcast
+      # (POST /payments/{id}/transactions/{transaction_id}/redrive).
+      #
+      # For the one shape a retry can fix: a transaction that is `pending` and whose
+      # SIGNED bytes the gateway already holds — prepared and signed, never landed on the
+      # chain (a worker that died between the two, a queue drained by hand). Nothing about
+      # the payment changes; the same bytes go back to the broadcaster.
+      #
+      # Offer this on the transaction's `redrivable` flag, which is the same predicate the
+      # gateway guards the route with — not on `status == "pending"`. A pending row holding
+      # no signed transaction is NOT redrivable, and there the next step is submitting the
+      # signature, not retrying a send that never happened.
+      #
+      # The transaction id is resolved THROUGH the payment, so one belonging to another
+      # payment answers 404 rather than redriving someone else's row.
+      #
+      # @param id [String] Payment UUID or rail0_id.
+      # @param transaction_id [String] The transaction row to redrive.
+      # @return [Hash] The transaction, re-enqueued.
+      def redrive(id, transaction_id)
+        http.post("/payments/#{id}/transactions/#{transaction_id}/redrive", {})
+      end
+
+      # Submit the payer's EIP-712 signature (PUT /payments/{id}/sign).
+      # @param id [String] Payment UUID or rail0_id.
+      # @param params [Hash] { signature: "0x…" } (65-byte 0x-prefixed hex).
+      # @return [Hash]
+      def sign(id, params)
+        http.put("/payments/#{id}/sign", params)
+      end
+
+      # List a payment's dispute open/close history.
+      # @param id [String] Payment UUID or rail0_id.
+      # @param status [String, nil] Filter by dispute status ("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 disputes(id, 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("/payments/#{id}/disputes#{query}")
+      end
+
+      # Build the unsigned transaction for an operation
+      # (POST /payments/{id}/{op}/prepare). +body+ carries operation-specific
+      # fields: amount (capture, refund), signature (refund phase-2), from
+      # (release). On the refund prepare, omitting the signature returns the
+      # EIP-3009 signing payload (refund phase-1) instead of an unsigned tx.
+      # @param id [String] Payment UUID or rail0_id.
+      # @param operation [String] One of {OPERATIONS}.
+      # @param body [Hash, nil] Operation-specific fields.
+      # @return [Hash]
+      # Pass +idempotency_key+ to make a repeat safe. Without one, a retry that
+      # arrives AFTER the first transaction was signed and broadcast opens a SECOND
+      # one — right for a genuine sequential partial capture, wrong for a retry, and
+      # nothing but the caller can tell those apart. Replaying a key returns the
+      # transaction the first call created (HTTP 200 rather than 201); the same key
+      # with different terms is refused 422 +idempotency_key_reused+. Scoped to this
+      # payment. (rail0-gateway#331)
+      def prepare(id, operation, body = nil, idempotency_key: nil)
+        http.post("/payments/#{id}/#{operation}/prepare", body,
+                  headers: idempotency_headers(idempotency_key))
+      end
+
+      # Broadcast a signed transaction for an operation (POST /payments/{id}/{op}); HTTP 202.
+      # @param id [String] Payment UUID or rail0_id.
+      # @param operation [String] One of {OPERATIONS}.
+      # @param params [Hash] { signed_transaction: "0x…" }.
+      # @return [Hash]
+      def submit(id, operation, params)
+        http.post("/payments/#{id}/#{operation}", params)
+      end
+
+      # Record a transaction the caller broadcast themselves (MetaMask/wallet flow)
+      # for an operation (POST /payments/{id}/{op}/submitted); HTTP 202.
+      # @param id [String] Payment UUID or rail0_id.
+      # @param operation [String] One of {OPERATIONS}.
+      # @param params [Hash] { transaction_hash: "0x…" }.
+      # @return [Hash]
+      def submit_by_hash(id, operation, params)
+        http.post("/payments/#{id}/#{operation}/submitted", params)
+      end
+
+      # Phase 1 — build the unsigned authorize() transaction (escrow hold).
+      def authorize_prepare(id, idempotency_key: nil)
+        prepare(id, "authorize", nil, idempotency_key: idempotency_key)
+      end
+
+      # Phase 2 — submit the signed authorize transaction.
+      def authorize(id, params)
+        submit(id, "authorize", params)
+      end
+
+      # Phase 1 — build the unsigned charge() transaction (one-shot authorize+capture).
+      def charge_prepare(id, idempotency_key: nil)
+        prepare(id, "charge", nil, idempotency_key: idempotency_key)
+      end
+
+      # Phase 2 — submit the signed charge transaction.
+      def charge(id, params)
+        submit(id, "charge", params)
+      end
+
+      # Phase 1 — build the unsigned capture() transaction. +amount+ is required.
+      def capture_prepare(id, amount, idempotency_key: nil)
+        prepare(id, "capture", { amount: amount }, idempotency_key: idempotency_key)
+      end
+
+      # Phase 2 — submit the signed capture transaction.
+      def capture(id, params)
+        submit(id, "capture", params)
+      end
+
+      # Phase 1 — build the unsigned void() transaction. Valid only while nothing
+      # has been captured yet; after any capture the contract reverts AlreadyCaptured
+      # (use {release_prepare} to return the uncaptured remainder instead).
+      def void_prepare(id, idempotency_key: nil)
+        prepare(id, "void", nil, idempotency_key: idempotency_key)
+      end
+
+      # Phase 2 — submit the signed void transaction.
+      def void(id, params)
+        submit(id, "void", params)
+      end
+
+      # Phase 1 — build the unsigned release() transaction. +from+ overrides the
+      # submitter address (defaults to the payer). Returns uncaptured escrow to the
+      # payer.
+      def release_prepare(id, from: nil, idempotency_key: nil)
+        prepare(id, "release", from ? { from: from } : {}, idempotency_key: idempotency_key)
+      end
+
+      # Phase 2 — submit the signed release transaction.
+      def release(id, params)
+        submit(id, "release", params)
+      end
+
+      # Two-phase EIP-3009 refund.
+      # Phase 1: pass only +amount+ → returns a signing payload for the payee to sign.
+      # Phase 2: pass +amount+ and +signature+ → returns the unsigned refund tx.
+      # @param id [String] Payment UUID or rail0_id.
+      # @param amount [String] Amount to refund, as a human decimal (e.g. "20.00").
+      # @param signature [String, nil] Payee's EIP-3009 signature (0x…), phase 2 only.
+      # @return [Hash]
+      def refund_prepare(id, amount:, signature: nil, idempotency_key: nil)
+        body = { amount: amount }
+        body[:signature] = signature unless signature.nil?
+        prepare(id, "refund", body, idempotency_key: idempotency_key)
+      end
+
+      # Phase 2 — submit the signed refund transaction.
+      def refund(id, params)
+        submit(id, "refund", params)
+      end
+
+      # Phase 1 — build the unsigned dispute() transaction (payer only).
+      # @param id [String] Payment UUID or rail0_id.
+      # @param reason [String, nil] Optional bytes32 code (0x…); defaults to zero server-side.
+      # @return [Hash]
+      def dispute_prepare(id, reason: nil, idempotency_key: nil)
+        prepare_dispute("dispute/prepare", id, reason, idempotency_key: idempotency_key)
+      end
+
+      # Phase 2 — submit the signed dispute transaction (payer only).
+      # @param id [String] Payment UUID or rail0_id.
+      # @param params [Hash] { signed_transaction: "0x…" }.
+      # @return [Hash]
+      def dispute(id, params)
+        http.post("/payments/#{id}/dispute", params)
+      end
+
+      # Phase 1 — build the unsigned closeDispute() transaction (payer only).
+      # @param id [String] Payment UUID or rail0_id.
+      # @param reason [String, nil] Optional bytes32 code (0x…).
+      # @return [Hash]
+      def close_dispute_prepare(id, reason: nil, idempotency_key: nil)
+        prepare_dispute("dispute/close/prepare", id, reason, idempotency_key: idempotency_key)
+      end
+
+      # Phase 2 — submit the signed close-dispute transaction (payer only).
+      # @param id [String] Payment UUID or rail0_id.
+      # @param params [Hash] { signed_transaction: "0x…" }.
+      # @return [Hash]
+      def close_dispute(id, params)
+        http.post("/payments/#{id}/dispute/close", params)
+      end
+
+      # The payer's counterpart to {#submit_by_hash}, which covers only the operations
+      # under /payments/{id}/{operation}/submitted — the two dispute paths are not shaped
+      # that way (`dispute/close` is two segments), so they need their own methods. Both
+      # exist in rail0-go and rail0-ts; without them a Ruby caller signing with a wallet
+      # that broadcasts on its own (MetaMask) could open and close disputes with a raw
+      # signed transaction, but never report one it had already sent. (#19)
+      #
+      # Payer-only, and the payer authenticates account-less via SIWE: a bare hash
+      # carries no signature, so the session is what proves who is reporting it.
+
+      # Report an already-broadcast dispute transaction by hash (payer only); HTTP 202.
+      # @param id [String] Payment UUID or rail0_id.
+      # @param params [Hash] { transaction_hash: "0x…" }.
+      # @return [Hash]
+      def dispute_submit_by_hash(id, params)
+        http.post("/payments/#{id}/dispute/submitted", params)
+      end
+
+      # Report an already-broadcast close-dispute transaction by hash (payer only); HTTP 202.
+      # @param id [String] Payment UUID or rail0_id.
+      # @param params [Hash] { transaction_hash: "0x…" }.
+      # @return [Hash]
+      def close_dispute_submit_by_hash(id, params)
+        http.post("/payments/#{id}/dispute/close/submitted", params)
+      end
+
+      private
+
+      def prepare_dispute(path, id, reason, idempotency_key: nil)
+        body = reason ? { reason: reason } : {}
+        http.post("/payments/#{id}/#{path}", body,
+                  headers: idempotency_headers(idempotency_key))
+      end
+
+      # {} when no key, so an un-keyed call sends exactly the headers it sent before.
+      def idempotency_headers(key)
+        key ? { "Idempotency-Key" => key } : {}
+      end
+    end
+  end
+end

data/lib/rail0/resources/query.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require "cgi"
+
+module Rail0
+  module Resources
+    # Shared query-string builder for resource classes. Included so every
+    # resource turns keyword filters into a URL query the same way: nil values
+    # are dropped, and booleans/integers are stringified.
+    module Query
+      private
+
+      def build_query(**params)
+        pairs = params.compact.map { |k, v| "#{k}=#{CGI.escape(v.to_s)}" }
+        pairs.empty? ? "" : "?#{pairs.join('&')}"
+      end
+    end
+  end
+end

data/lib/rail0/resources/tokens.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require_relative "query"
+
+module Rail0
+  module Resources
+    # Public token catalog (GET /tokens, no auth).
+    class Tokens
+      include Query
+
+      attr_reader :http
+
+      def initialize(http)
+        @http = http
+        freeze
+      end
+
+      # List active tokens, optionally filtered by chain and/or symbol.
+      # @param chain_id [Integer, nil] Chain ID to filter by. Pass nil or 0 for all chains.
+      # @param symbol [String, nil] Filter by token symbol (case-insensitive, e.g. "USDC").
+      # @return [Array<Hash>] chain_id, symbol, address, decimals
+      def list(chain_id: nil, symbol: nil)
+        chain_id = nil if chain_id == 0
+        http.get("/tokens#{build_query(chain_id: chain_id, symbol: symbol)}")
+      end
+    end
+  end
+end

data/lib/rail0/resources/wallets.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+require_relative "query"
+
+module Rail0
+  module Resources
+    # Account-scoped wallet management (requires JWT).
+    #
+    # Wallets live under /accounts/{account_id}/wallets, so every method takes the
+    # account id as its first argument. +list+ returns the account's wallets, each
+    # with its token holdings nested under +tokens+ (a wallet with no matching
+    # tokens is still returned with an empty list). +id_or_address+ accepts either
+    # the wallet UUID or its 0x address (unique per account).
+    class Wallets
+      include Query
+
+      attr_reader :http
+
+      def initialize(http)
+        @http = http
+        freeze
+      end
+
+      # List the account's wallets, each with nested token holdings.
+      # @param account_id [String] Account UUID.
+      # @param chain_id [Integer, nil] Restrict nested tokens to this chain id.
+      # @param token_symbol [String, nil] Restrict nested tokens to this symbol (e.g. "USDC").
+      # @param active [Boolean, nil] Filter wallets by active flag.
+      # @param default [Boolean, nil] Restrict nested holdings to the default one.
+      # @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(account_id, chain_id: nil, token_symbol: nil, active: nil, default: nil,
+               sort: nil, page: nil, per_page: nil)
+        query = build_query(chain_id: chain_id, token_symbol: token_symbol, active: active,
+                            default: default, sort: sort, page: page, per_page: per_page)
+        http.get_list("/accounts/#{account_id}/wallets#{query}")
+      end
+
+      # Fetch a single wallet by its id or 0x address.
+      # @param account_id [String] Account UUID.
+      # @param id_or_address [String] Wallet UUID or 0x address.
+      # @return [Hash] id, address, label, active
+      def get(account_id, id_or_address)
+        http.get("/accounts/#{account_id}/wallets/#{id_or_address}")
+      end
+
+      # Add a wallet to the account.
+      #
+      # Requires a SIWE PROOF-OF-OWNERSHIP of the address being added, not merely
+      # the session JWT: the gateway verifies that +signature+ recovers to
+      # +address+ (422 otherwise), consumes the nonce carried in +message+, and
+      # enforces global address uniqueness (409 if registered anywhere). The proven
+      # address need not be the session address — a merchant may control several
+      # payee wallets.
+      #
+      # Obtain the pair from Auth#prove_address, which signs with the WALLET-LINK
+      # statement. A login proof is refused with 422 siwe_purpose_mismatch, so the
+      # message cannot simply be one taken from #login.
+      #
+      #   proof = client.auth.prove_address(private_key: added_key, domain: "api.rail0.xyz")
+      #   client.wallets.create(account_id, address: added, **proof, label: "Payouts")
+      #
+      # @param account_id [String] Account UUID.
+      # @param address [String] EVM wallet address (0x, 42 chars) — the address the proof is for.
+      # @param message [String] EIP-4361 SIWE message signed by +address+ (from Auth#prove_address).
+      # @param signature [String] Signature over +message+ (0x…), proving control of +address+.
+      # @param label [String, nil] Human-readable label.
+      # @return [Hash] id, address, label, active
+      def create(account_id, address:, message:, signature:, label: nil)
+        body = { address: address, message: message, signature: signature }
+        body[:label] = label unless label.nil?
+        http.post("/accounts/#{account_id}/wallets", body)
+      end
+
+      # Update a wallet's label and/or active status.
+      # @param account_id [String] Account UUID.
+      # @param id_or_address [String] Wallet UUID or 0x address.
+      # @param label [String, nil] New label.
+      # @param active [Boolean, nil] New active status.
+      # @return [Hash] id, address, label, active
+      def update(account_id, id_or_address, label: nil, active: nil)
+        body = {}
+        body[:label]  = label  unless label.nil?
+        body[:active] = active unless active.nil?
+        http.patch("/accounts/#{account_id}/wallets/#{id_or_address}", body)
+      end
+
+      # Soft-delete (deactivate) a wallet. Returns HTTP 204.
+      # @param account_id [String] Account UUID.
+      # @param id_or_address [String] Wallet UUID or 0x address.
+      # @return [nil]
+      def delete(account_id, id_or_address)
+        http.delete("/accounts/#{account_id}/wallets/#{id_or_address}")
+      end
+
+      # Read a wallet's live on-chain balances across the configured chains. Each
+      # per-chain entry carries the native gas-token balance plus the active ERC-20
+      # token balances, or an in-band error when that chain's RPC was unreachable
+      # (one dead RPC never hides the other chains' balances).
+      # @param account_id [String] Account UUID.
+      # @param id_or_address [String] Wallet UUID or 0x address.
+      # @param chain_id [Integer, nil] Restrict to one chain id (default: all configured chains).
+      # @param token_symbol [String, nil] Restrict tokens to this symbol (default: all active tokens).
+      # @return [Hash] wallet_id, address, balances
+      def balances(account_id, id_or_address, chain_id: nil, token_symbol: nil)
+        query = build_query(chain_id: chain_id, token_symbol: token_symbol)
+        http.get("/accounts/#{account_id}/wallets/#{id_or_address}/balances#{query}")
+      end
+
+      # ── Token holdings ────────────────────────────────────────────────────────
+      # Which tokens a wallet accepts, on which chains. This is what GET
+      # /payment_methods then exposes to buyers, so a merchant onboarding flow that
+      # can create a wallet but not configure its tokens cannot finish. (#12)
+
+      # Accept a token (on a chain) on this wallet.
+      #
+      # Idempotent by (wallet, chain, token): re-adding an existing holding
+      # re-enables it and returns 200 rather than creating a second row (201 is the
+      # first-time answer). `default` makes it the wallet's default token, which is
+      # the one a buyer is offered first.
+      #
+      # @param account_id [String] Account UUID.
+      # @param id_or_address [String] Wallet UUID or 0x address.
+      # @param chain_id [Integer] EVM chain id of the token.
+      # @param token [String] Token address (0x, 40 hex).
+      # @param default [Boolean, nil] Make this the wallet's default token.
+      # @return [Hash] the token holding
+      def add_token(account_id, id_or_address, chain_id:, token:, default: nil)
+        body = { chain_id: chain_id, token: token }
+        body[:default] = default unless default.nil?
+        http.post("/accounts/#{account_id}/wallets/#{id_or_address}/tokens", body)
+      end
+
+      # Stop accepting a token on this wallet (soft delete). Returns HTTP 204.
+      #
+      # `token_id` is the id of the HOLDING as returned by {add_token} / {list}'s
+      # nested `tokens`, not the token's contract address.
+      #
+      # @return [nil]
+      def remove_token(account_id, id_or_address, token_id)
+        http.delete("/accounts/#{account_id}/wallets/#{id_or_address}/tokens/#{token_id}")
+      end
+
+      # Re-enable an existing token holding.
+      # @return [Hash] the token holding
+      def enable_token(account_id, id_or_address, token_id)
+        http.patch("/accounts/#{account_id}/wallets/#{id_or_address}/tokens/#{token_id}/enable")
+      end
+
+      # Disable an existing token holding without forgetting it — the holding (and
+      # its default flag) survives, so re-enabling restores the previous setup.
+      # @return [Hash] the token holding
+      def disable_token(account_id, id_or_address, token_id)
+        http.patch("/accounts/#{account_id}/wallets/#{id_or_address}/tokens/#{token_id}/disable")
+      end
+    end
+  end
+end