rail0-sdk 1.8.1 → 1.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: eaaadaf08346573c426e649979548088c8cbbb1a2b037e63026c5512fa44feb8
-  data.tar.gz: b4eea2d0cd8cb675f2d31e5fbddee08f62fd3421f2cb969db246fc8e4d4338fb
+  metadata.gz: ef5875508f67b6ca5ba08aa397f5afa33ad2fb1d3c53d956c1ea5c1f6f0c066c
+  data.tar.gz: 251404c40cce8af924a7b0ffded8052adb3a0fdea8c0f91345a3a9f7dceae3ba
 SHA512:
-  metadata.gz: 9433218dbe34e8d9a6cf7c200aca99d15695940fc099e5347b85e14c9612dbef6d824c303b3cd52e81e00787c25a0c2459cc40aa5e62bd0adb4555294f984816
-  data.tar.gz: 5e185810e4e78e7282ceda6760e5c2ee2857bf7c5469806fbb48fdc92fed12592fd8367aa1707bdafc76a52d4d7e65251d3dce36222174434bce9c53125398ff
+  metadata.gz: d3bcef6de15169f95b428d03e16336373f1e234b3c4a7e3aa987ddd72a9e34cdeddb7bb0359e0b03534c60209e89dc50e7a0014d45ff2b4e0c676b2e34df98d4
+  data.tar.gz: 8d2d98affb4443432e676d9008aa0a73486946884fc5905e2a44b99fdbad75eec123217b10d4818de8df29d2aad98e410c621552ce435697a5bb0988fcb70bd9

data/README.md

@@ -301,11 +301,17 @@ logging — it says exactly which sessions died, which `revoked_all: true` canno
 ```ruby
 client.chains.list                                    # GET /blockchains (each chain's :contract is the active RAIL0 deployment, :settlement its measured confirm time)
 client.chains.list(network_type: "testnet", symbol: "ETH")
+Rail0::Resources::Chains.resolve(client.chains.list(network_type: "testnet"), "arc")  # by slug (case-insensitive) or chain id; raises on no match / an ambiguous slug
 client.tokens.list                                    # GET /tokens — every token, retired ones included
 client.tokens.list(chain_id: 84532, symbol: "USDC")
 client.tokens.list(active: true)                      # what a NEW payment may use
 ```
 
+Each chain carries a `slug` (e.g. `"arc"`, shared by its testnet and mainnet, unique per
+`network_type`) and `public_rpc_urls` (keyless RPC endpoints the gateway publishes for
+clients). `Chains.resolve(chains, ref)` picks one by chain id or slug without a request; a
+slug matching both networks in the list raises, so filter with `network_type:` or pass the id.
+
 Each chain's `settlement` is how long an operation on it has taken to confirm **on this
 gateway**, end to end (the chain's finality lag plus the gateway/indexer pipeline):
 `{ p50_seconds:, p90_seconds:, sample_size:, window_days: }`, percentiles of broadcast →
@@ -335,7 +341,7 @@ client.health.get   # GET /health → { status:, api_version:, contract_version:
 
 ## Pagination
 
-Paginated calls return `{ data:, meta: }`. `meta` is `{ page:, per_page:, total:, total_pages:, links: }`.
+Paginated calls return `{ data:, meta: }`. `meta` is `{ page:, per_page:, total:, total_pages:, links:, next_cursor: }`.
 
 `page` is 1-based and bounded to 1..1,000,000 — a value outside is a 400, not an empty
 page. `per_page` defaults to 25 and is capped at 100.
@@ -349,6 +355,22 @@ while page[:meta][:links][:next]
 end
 ```
 
+`payments.list` and `payouts.list` also page by **cursor**: pass `after:` (omit it on the
+first page) and follow `meta[:next_cursor]` until it is `nil`. It walks newest first at a
+constant cost per page and carries no total (`total` reads 0); `page:` or a sort other than
+`-created_at` beside `after:` is 422 `invalid_cursor`. `next_cursor` comes from the
+`x-next-cursor` header, or the Link `next`'s `after` when the header is missing, and is
+`nil` on offset pages.
+
+```ruby
+cursor = nil
+loop do
+  page = client.payouts.list(per_page: 100, after: cursor)
+  page[:data].each { |payout| puts payout[:id] }
+  break unless (cursor = page[:meta][:next_cursor])
+end
+```
+
 ### Idempotent prepares
 
 Every `*_prepare` takes an optional `idempotency_key:`. 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 only the caller can tell those apart. Replaying a key returns the first transaction; the same key with different terms is refused `422 idempotency_key_reused`.
@@ -625,12 +647,184 @@ client.payments.submit(id, "capture", { signed_transaction: raw })
 client.payments.submit_by_hash(id, "capture", { transaction_hash: "0x…" })
 ```
 
+## Payouts (JWT)
+
+A payout moves the merchant wallet's balance to a **payout destination** — a deposit
+address at an exchange, Circle Mint, an off-ramp provider or your own custody. It is a
+plain ERC-20 `transfer(address,uint256)` from the wallet, signed by the destination's own
+wallet; rail0 never holds the key. Destination amounts (`min_amount`) are **base-unit**
+strings; the `*_formatted` fields beside them carry the human decimals.
+
+### 1. Register a destination (with the confirmation)
+
+Generate the deposit address at the venue **with the network set to the payout's chain**,
+note the venue's minimum deposit, then register it. The minimum is required, as exactly one
+of `min_amount:` (the venue's figure in base units, from its deposit page) or
+`no_minimum: true` (the merchant states the venue has none). Neither, a blank figure, or both
+raise `ArgumentError` before anything is sent, and nothing is defaulted: a minimum nobody
+looked up is how a deposit gets lost. `confirm_details:` is required and has
+no default: `true` is the merchant's acceptance of the gateway's `details_v1` text
+(`Rail0::Resources::PayoutDestinations::CONFIRM_DETAILS_TEXT`), recorded with who and when:
+
+> I have checked the address, network, token and minimum deposit on the venue's deposit
+> page and confirm they are correct. Funds sent to a wrong address or network, or below the
+> venue's minimum, may be permanently lost and cannot be recovered by rail0.
+
+Show that text and pass the merchant's answer; anything but `true` is 422
+`confirmation_required` and nothing is saved.
+
+`label:` is required too: the name the merchant knows the destination by. The gateway trims
+it, and it must be unique among the account's live destinations, compared without regard to
+case (409 `payout_destination_label_taken`; deleting a destination frees its label). A blank
+or whitespace-only label raises `ArgumentError` before anything is sent (the gateway's 422
+`label_required`).
+
+```ruby
+dest = client.payout_destinations.create(
+  wallet_id: WALLET_ID,               # the session's own wallet (uuid or address)
+  chain_id: 5042002, token: USDC, address: VENUE_DEPOSIT_ADDRESS,
+  label: "Kraken",                    # required, unique per account (case-insensitive)
+  min_amount: "5000000",              # the venue's minimum, base units (5 USDC) — or no_minimum: true
+  confirm_details: merchant_accepted  # true only once the merchant accepted the text above
+)
+dest[:status]                         # => "unverified"
+
+client.payout_destinations.list(status: "verified")       # paged like payments
+client.payout_destinations.list(include_deleted: true)     # deleted ones too (deleted_at set)
+client.payout_destinations.get(dest[:id])
+client.payout_destinations.events(dest[:id])               # audit trail, newest first
+```
+
+### 2. Prove it: proof → confirm
+
+An unverified destination can receive the **proof** amount at most: a small test transfer
+(the gateway's proof amount, raised to `min_amount` when that is higher). Send it, wait for
+it to confirm on-chain, check that the venue **credited** it, then confirm:
+
+```ruby
+proof = client.payouts.prepare(destination_id: dest[:id], purpose: "proof")
+client.payouts.sign_and_submit(proof, MERCHANT_PRIVATE_KEY, destination: dest)
+# … poll client.payouts.get(proof[:id]) until status == "confirmed", check the venue …
+client.payout_destinations.confirm(dest[:id])              # => status "verified"
+```
+
+### 3. Pay out: prepare → verify → sign → submit
+
+`amount` is a **human decimal** or `"all"` (the balance minus what is kept back, below). A payout
+below the destination's `min_amount` is refused 422 `payout_below_minimum`.
+
+```ruby
+payout = client.payouts.prepare(destination_id: dest[:id], amount: "250.00")
+client.payouts.sign_and_submit(payout, MERCHANT_PRIVATE_KEY,
+                               destination: dest, amount: "250.00", decimals: 6)
+# 202, now "submitted"; poll client.payouts.get(payout[:id]) (or the payouts.confirmed /
+# payouts.failed webhooks) until it settles
+```
+
+`sign_and_submit` is `Rail0::Signing.sign_payout` + `payouts.submit`. Before the key touches
+the prepared `unsigned_transaction`, `Rail0::PayoutVerify.verify` holds it to exactly:
+`to` = the payout's token, `value` 0, `chain_id` = the payout's chain, and calldata
+`0xa9059cbb` + abi(the payout's address, the payout's base-unit amount) with nothing
+trailing. With `destination:` the payout must also be for that registered destination
+(chain, token, address); with `amount:` + `decimals:` its amount must be exactly the one you
+asked for. Anything else raises `Rail0::TxVerify::RefusedSignature` and nothing is signed or
+sent. There is no blind form.
+
+The two steps apart, or the other way to send:
+
+```ruby
+raw = Rail0::Signing.sign_payout(payout, MERCHANT_PRIVATE_KEY, destination: dest,
+                                 amount: "250.00", decimals: 6)
+client.payouts.submit(payout[:id], { signed_transaction: raw })   # the gateway broadcasts
+
+# A wallet that signs and broadcasts itself: verify, send, then report the hash.
+Rail0::PayoutVerify.verify(payout[:unsigned_transaction], payout: payout, destination: dest,
+                           amount: "250.00", decimals: 6)
+client.payouts.submit_by_hash(payout[:id], { transaction_hash: "0x…" })
+
+client.payouts.resend(payout[:id])  # re-broadcast the stored signed bytes (after a 502)
+client.payouts.cancel(payout[:id])  # an UNSIGNED pending payout only
+client.payouts.list(status: %w[pending submitted], purpose: "payout")
+client.payouts.events(payout[:id])
+```
+
+One pending payout per destination: preparing again replaces it while it is unsigned. Once
+a signed transaction is stored, it may still be mined, so it cannot be re-prepared or
+cancelled (409 `payout_already_signed`): `resend` it and let it settle.
+
+A runnable end-to-end flow (register → proof → confirm → payout → poll) is in
+[`examples/06_payouts.rb`](examples/06_payouts.rb).
+
+### Minimum, reserves, disable and delete
+
+- **Minimum** (`min_amount`): the venue's minimum deposit. Below it the venue may never
+  credit a transfer, so the gateway refuses it. It is required and explicit: a figure
+  (`"0"` included), or `no_minimum: true` when the venue has none — the destination then
+  reads `no_minimum: true` with `min_amount` nil (`no_minimum: false` with a nil `min_amount`
+  is a destination registered before the minimum was asked: never stated). A blank figure,
+  or a figure beside `no_minimum: true`, raises `ArgumentError` (the gateway's
+  `minimum_required` / `minimum_conflict`). Changing either needs the same confirmation, and
+  raising the minimum above the latest proof takes the verification away (prove it again):
+
+  ```ruby
+  client.payout_destinations.update(dest[:id], min_amount: "10000000", confirm_details: merchant_accepted)
+  client.payout_destinations.update(dest[:id], no_minimum: true, confirm_details: merchant_accepted) # none
+  ```
+
+- **Reserves**: what a payout keeps back in the wallet is decided at payout time, not stored
+  on the destination. The **refund reserve** is the refundable balance of the wallet's
+  payments in this token still inside their refund window (a refund is pulled from the payee
+  wallet, so an emptied wallet fails it). The **gas reserve**, only on a chain whose gas is
+  paid in this very token (Arc's USDC, `native_gas`), is the gas for those refunds and for
+  capturing the open authorizations plus a base of new captures; `"0"` elsewhere. On such a
+  chain the payout's own fee (`gas_allowance`) is always kept back too. `reserves` shows the
+  figures right now, with `available`: what `"all"` moves with both reserves kept:
+
+  ```ruby
+  r = client.payout_destinations.reserves(dest[:id])
+  r[:refund_reserve_formatted]  # => "40.00"   (r[:refundable_payments] payments)
+  r[:gas_reserve_formatted]     # => "0.12"
+  r[:available_formatted]       # => "960.00"  what amount: "all" moves
+  ```
+
+  Both reserves are kept by default. A payout can opt out of either (a refund or capture after
+  it may then fail for lack of funds); the payout records what it kept back in
+  `refund_reserve` / `gas_reserve` (base units, nil for a proof):
+
+  ```ruby
+  client.payouts.prepare(destination_id: dest[:id], amount: "all", keep_refund_reserve: false)
+  client.payouts.prepare(destination_id: dest[:id], amount: "all", keep_gas_reserve: false)
+  ```
+
+- **Rename**: `label:` renames it, under the same rules as on create: never blank
+  (`ArgumentError` here, 422 `label_required` at the gateway) and unique per account,
+  case-insensitive (409 `payout_destination_label_taken`):
+
+  ```ruby
+  client.payout_destinations.update(dest[:id], label: "Kraken main")
+  ```
+
+- **Disable and delete**: `active: false` disables a destination (`true` re-enables it with
+  the verification it had). `delete` removes it from the lists and frees its payment method
+  (one destination per token and chain, so another address can be registered there) and its
+  label; the row is kept (`get` and `events` still read it, with `deleted_at` set
+  and `status` `"disabled"`). Either settles a pending payout first: an unsigned one is
+  cancelled, a signed one refuses with 409 `payout_already_signed`.
+
+  ```ruby
+  client.payout_destinations.update(dest[:id], active: false)  # disable (true re-enables)
+  client.payout_destinations.delete(dest[:id])                 # soft delete, own wallet only
+  ```
+
 ## Webhooks (JWT)
 
 One subscription carries a **set** of topics (see `Rail0::Resources::Webhooks::TOPICS`):
 one shared secret and one circuit breaker for all of them, with each delivery naming the
 event that fired in `X-Rail0-Topic`. Two subscriptions for the same `callback_url` must not
-overlap — the gateway answers 409 and names the topic that collided.
+overlap — the gateway answers 409 and names the topic that collided. The payout topics —
+`payouts.confirmed`, `payouts.failed` (the reason is the payout's `error_code`) and
+`payout_destinations.verified` — carry the same envelope (`id`, `emitted_at`, `topic`) with
+the subject under `payout` or `payout_destination` instead of `payment`/`transaction`.
 
 ```ruby
 hook = client.webhooks.create(
@@ -867,6 +1061,8 @@ Requires the `eth` gem. No private key ever leaves your process.
 | `Rail0::PayloadVerify.verify(signing_payload, payment:, signer:, amount: nil)` | The payload pre-sign check on its own — run it before handing the payload to a browser wallet |
 | `sign_transaction(unsigned_transaction, key, payment:, operation:, amount: nil)` | Verify a prepare step's unsigned EIP-1559 transaction against the payment, then sign it; returns the 0x raw tx. Without `payment:` it signs blindly (**deprecated**) |
 | `Rail0::TxVerify.verify(unsigned_transaction, payment:, operation:, amount: nil, signer: nil)` | The pre-sign check on its own — for a signer that is not a local key |
+| `sign_payout(payout, key, destination: nil, amount: nil, decimals: nil)` | Verify a prepared payout's ERC-20 transfer (see [Payouts](#payouts-jwt)), then sign it; returns the 0x raw tx. No blind form |
+| `Rail0::PayoutVerify.verify(unsigned_transaction, payout:, destination: nil, amount: nil, decimals: nil, signer: nil)` | The payout pre-sign check on its own — for a wallet that broadcasts itself |
 | `sign_transfer_with_authorization(signer, domain, params)` | Raw EIP-3009 `TransferWithAuthorization` signer, for talking to a token directly |
 
 ```ruby
@@ -1058,6 +1254,7 @@ lib/rail0/
   signing.rb           EIP-3009 + EIP-1559 signing (requires 'eth')
   tx_verify.rb         Rail0::TxVerify — pre-sign check of an unsigned transaction
   payload_verify.rb    Rail0::PayloadVerify — pre-sign check of an EIP-3009 signing payload
+  payout_verify.rb     Rail0::PayoutVerify — pre-sign check of a payout's ERC-20 transfer
   stablecoins.rb       stablecoin address registry
   dispute_reasons.rb   generated Rail0::DisputeReasons — the dispute-reason dictionary
   types.rb             generated Struct docs of the gateway schema (reference only)
@@ -1074,6 +1271,8 @@ lib/rail0/
     accounts.rb        the caller's own account profile, read and update (JWT)
     webhooks.rb        webhook subscription management (JWT)
     analytics.rb       account-scoped payment analytics (JWT)
+    payout_destinations.rb payout destinations: register, confirm, update, delete, reserves (JWT)
+    payouts.rb         merchant payouts: prepare, sign, submit (JWT)
     query.rb           shared query-string and path-segment helpers
 ```
 
@@ -1115,7 +1314,8 @@ A release is an approved pull request: merging it is what publishes.
    **Or on a feature branch**, to release a change in the same review: run it on a clean
    branch that is pushed, contains `origin/main` and has an open pull request into `main`.
    The bump is committed and pushed on that branch (`chore(release): vX.Y.Z`), the pull
-   request's own title counts toward the version and gets a line in the notes, and the
+   request's own title counts toward the version, gets a line in the notes and gains a
+   ` (release vX.Y.Z)` suffix, and the
    notes go into its description between `<!-- release:start -->` markers — the text above
    them is kept. Re-run it after new commits or a merge of `main`: it refreshes the version
    and the notes instead of bumping twice. One approval then covers the change and its

data/lib/rail0/client.rb

@@ -12,6 +12,8 @@ require_relative "resources/payments"
 require_relative "resources/disputes"
 require_relative "resources/webhooks"
 require_relative "resources/analytics"
+require_relative "resources/payout_destinations"
+require_relative "resources/payouts"
 
 module Rail0
   # Entry point for the RAIL0 SDK.
@@ -48,8 +50,13 @@ module Rail0
     #   @return [Resources::Webhooks] Webhook subscription management (JWT).
     # @!attribute [r] analytics
     #   @return [Resources::Analytics] Account-scoped payment analytics (JWT).
+    # @!attribute [r] payout_destinations
+    #   @return [Resources::PayoutDestinations] Where the merchant's payouts go (JWT).
+    # @!attribute [r] payouts
+    #   @return [Resources::Payouts] Merchant payouts: prepare, sign, submit (JWT).
     attr_reader :auth, :chains, :tokens, :health, :payment_methods,
-                :accounts, :wallets, :payments, :disputes, :webhooks, :analytics
+                :accounts, :wallets, :payments, :disputes, :webhooks, :analytics,
+                :payout_destinations, :payouts
 
     # @param base_url [String] Base URL of the RAIL0 API, e.g. "https://api.rail0.xyz".
     # @param headers [Hash] Default headers merged into every request (e.g. Authorization).
@@ -83,6 +90,8 @@ module Rail0
       @disputes        = Resources::Disputes.new(http)
       @webhooks        = Resources::Webhooks.new(http)
       @analytics       = Resources::Analytics.new(http)
+      @payout_destinations = Resources::PayoutDestinations.new(http)
+      @payouts             = Resources::Payouts.new(http)
       freeze
     end
   end

data/lib/rail0/error_hints.rb

@@ -113,6 +113,30 @@ module Rail0
     "onboarding_link_invalid" => "the link was altered or its request no longer exists — use the link in the most recent email, or ask for a new one",
     "onboarding_link_expired" => "the link has expired — sign up again, or ask your RAIL0 contact for a new link",
     "onboarding_link_superseded" => "a newer link was sent for this request and this one no longer works — use the link in the most recent email",
+    # Payouts (gateway#455): the merchant's transfer of its balance to a payout destination.
+    "confirmation_required" => "registering a payout destination, or changing its min_amount or no_minimum, needs confirm_details: true — the merchant's confirmation that they checked the address, network, token and minimum deposit at the venue (PayoutDestinations::CONFIRM_DETAILS_TEXT)",
+    "payout_destination_exists" => "this payment method (token and chain) already has a destination — one per method; delete it to register another address (payout_destinations.list)",
+    "payout_destination_label_taken" => "another destination of this account already has this label (compared without regard to case) — pick another name, or delete that destination to free it (payout_destinations.list)",
+    "label_required" => "a payout destination needs a label — a name, not blank or whitespace (payout_destinations.create / update)",
+    "payout_destination_zero_address" => "the zero address cannot receive a payout — register the venue's deposit address",
+    "payout_destination_own_wallet" => "the destination is the paying wallet itself — register the deposit address of the exchange, Circle Mint account or another wallet you control",
+    "payout_destination_is_contract" => "the address is a RAIL0 contract or a token contract on this chain, where funds cannot be recovered — register the venue's deposit address",
+    "payout_destination_disabled" => "the destination is disabled — re-enable it (payout_destinations.update(id, active: true)) or choose another one",
+    "payout_destination_unverified" => "the destination is not verified: send the proof (payouts.prepare(purpose: \"proof\")), wait for it to confirm, check the venue credited it, then payout_destinations.confirm — until then only the proof amount can be sent",
+    "payout_destination_proof_missing" => "the proof transfer has not confirmed on-chain yet — prepare, sign and submit it (purpose: \"proof\"), wait for payouts.get to say confirmed, then confirm the destination",
+    "minimum_required" => "a payout destination needs its venue's minimum deposit: min_amount (base units, from the venue's deposit page), or no_minimum: true when the venue has none — a blank min_amount is not one (to remove a minimum, send no_minimum: true)",
+    "minimum_conflict" => "min_amount and no_minimum: true contradict each other — send the venue's minimum, or no_minimum: true when it has none, not both",
+    "payout_below_minimum" => "the amount is below the destination's min_amount (the venue may never credit it) — send at least the minimum; for \"all\", the balance after what is kept back (reserves, gas) is below it",
+    "insufficient_balance" => "the wallet does not hold enough of the token for this amount after what the payout keeps back (refund reserve, gas reserve, gas allowance) — the detail names what is available; payout_destinations.reserves(id) shows the figures",
+    "payout_limit_reached" => "this wallet reached its hourly payout limit — retry later",
+    "payout_already_signed" => "the payout already holds a signed transaction that may still be mined — resend it (payouts.resend) and let it settle; it cannot be re-prepared or cancelled",
+    "payout_not_pending" => "the payout is already submitted or settled — prepare a new one",
+    "payout_not_signed" => "the payout holds no signed transaction to resend — submit the signed transfer first",
+    "payout_hash_in_use" => "another payout already records this transaction hash — one transaction settles one payout",
+    "foreign_transfer_hash" => "the reported transaction does not move this payout's amount of its token to its destination — report the hash of the transfer you broadcast for this payout",
+    "invalid_amount" => "the amount is not valid: base units (digits only, below 2^120) for min_amount, a positive decimal within the token's decimals elsewhere",
+    "invalid_transaction" => "the signed transaction could not be decoded, or its sender is not allowed here — sign the prepare's unsigned_transaction unmodified with the right wallet",
+    "unknown_chain" => "that chain id is not configured on this gateway — see chains.list",
     # A BARE forbidden is not a party mismatch: the gateway split those into codes of
     # their own (not_the_payee, not_the_payer, wallet_deactivated, account_deactivated,
     # not_your_account) because they need different fixes. This entry kept describing

data/lib/rail0/http_client.rb

@@ -64,7 +64,8 @@ module Rail0
     # headers (not a {data, meta} envelope), so this reads the meta back from the
     # headers and wraps the array. Non-paginated array endpoints (blockchains,
     # tokens, payment_methods) use plain #get instead.
-    # @return [Hash] { data: Array<Hash>, meta: { page:, per_page:, total: } }
+    # @return [Hash] { data: Array<Hash>, meta: { page:, per_page:, total:, total_pages:, links:,
+    #   next_cursor: } } — next_cursor is set only on a cursor-paged list with a next page.
     def get_list(path)
       request(:get, path, nil, paginated: true)
     end

data/lib/rail0/payout_verify.rb

@@ -0,0 +1,211 @@
+# frozen_string_literal: true
+
+require_relative "tx_verify"
+
+module Rail0
+  # Pre-sign verification of a payout's +unsigned_transaction+ — {Rail0::TxVerify}'s
+  # counterpart for the merchant payout (POST /payouts/prepare).
+  #
+  # A payout is not a RAIL0 call: it is a plain ERC-20 +transfer(address,uint256)+ from the
+  # merchant's wallet, addressed to the TOKEN contract. For a plain transfer the calldata IS
+  # the money, so nothing in it may be skipped: a gateway endpoint that answered with
+  # +approve(attacker, MAX)+, a transfer to another address, a larger amount, another token
+  # or another chain would otherwise have the merchant's key sign it. Every check below runs
+  # on data the caller already holds, before the key touches the transaction. In order:
+  #
+  # 1. the JSON parses;
+  # 2. +value+ is zero — an ERC-20 transfer attaches no native currency;
+  # 3. +chain_id+ is the payout's +chain_id+;
+  # 4. +from+, when present, is the signing key's address;
+  # 5. +to+ is an address and is the payout's +token+ (case-insensitive) — an empty +to+
+  #    would be a contract creation and always refuses;
+  # 6. +data+ is EXACTLY +0xa9059cbb+ ++ abi(address = the payout's +address+, uint256 = the
+  #    payout's base-unit +amount+), nothing trailing.
+  #
+  # With +destination:+ (the record the merchant registered, from
+  # {Resources::PayoutDestinations#get}) the payout itself is first held to it: same
+  # destination id, chain, token and recipient address — so a payout "for" this destination
+  # that pays elsewhere refuses. With +amount:+ (the human decimal the caller asked
+  # {Resources::Payouts#prepare} for, not "all") the payout's base-unit amount must be exactly
+  # that amount scaled by +decimals:+.
+  #
+  # FAIL-CLOSED: a payout record missing its chain_id, token, address or a base-unit amount,
+  # or an explicit +amount:+ without +decimals:+, refuses rather than skips. A refusal raises
+  # {Rail0::TxVerify::RefusedSignature} ("refusing to sign: …", naming the field).
+  #
+  # Mirrors rail0-admin's lib/onchain-guard.ts (+assertTxTarget+ with a transfer, and
+  # +assertTransferCall+). Loaded by +rail0/signing+, never by +require "rail0"+ alone.
+  module PayoutVerify
+    # The 4-byte selector of ERC-20 +transfer(address,uint256)+ — keccak256 of that
+    # signature, pinned in the spec.
+    TRANSFER_SELECTOR = "a9059cbb"
+
+    # The one function a payout may call.
+    TRANSFER_SIGNATURE = "transfer(address,uint256)"
+
+    WORD_HEX = 64
+    private_constant :WORD_HEX
+
+    # Verifies +unsigned_transaction+ against +payout+ (and +destination+ / +amount+ when
+    # given), BEFORE any key touches it. Raises {Rail0::TxVerify::RefusedSignature} on the
+    # first mismatch; returns the parsed, string-keyed transaction otherwise.
+    #
+    # @param unsigned_transaction [String, Hash] the payout's +unsigned_transaction+
+    # @param payout [Hash] the prepared payout (+chain_id+, +token+, +address+, +amount+)
+    # @param destination [Hash, nil] the registered destination the payout must be for
+    # @param amount [String, nil] the human decimal passed to prepare; nil or "all" skips
+    #   only this comparison (the gateway chose the amount: a proof, or the balance)
+    # @param decimals [Integer, nil] the token's decimals, required with an explicit +amount+
+    # @param signer [String, nil] the address of the key about to sign, or nil to skip
+    # @return [Hash] the transaction, string-keyed
+    def self.verify(unsigned_transaction, payout:, destination: nil, amount: nil, decimals: nil, signer: nil)
+      tx  = parse(unsigned_transaction)
+      pay = payout_fields(payout)
+      check_destination(pay, destination) unless destination.nil?
+      check_amount(pay[:amount], amount, decimals)
+      check_header(tx, pay, signer)
+      check_call(tx["data"], pay[:address], pay[:amount])
+      tx
+    end
+
+    def self.parse(unsigned_transaction)
+      refuse("the payout carries no unsigned transaction") if blank?(unsigned_transaction)
+      tx = unsigned_transaction.is_a?(String) ? JSON.parse(unsigned_transaction) : unsigned_transaction
+      refuse("the unsigned transaction is not an object") unless tx.is_a?(Hash)
+      tx.transform_keys(&:to_s)
+    rescue JSON::ParserError => e
+      refuse("the gateway's unsigned transaction is not valid JSON: #{e.message}")
+    end
+
+    # The payout fields the transaction is held to. Every one is required: for a plain
+    # transfer there is nothing else to compare against.
+    def self.payout_fields(payout)
+      refuse("cannot check the transaction without the payout it is for") unless payout.is_a?(Hash)
+      p = symbolize(payout)
+      refuse("the payout's chain_id is unknown, so the chain cannot be checked") unless decimal?(p[:chain_id])
+      refuse("the payout's token is not an address, so the transfer cannot be checked") unless address?(p[:token])
+      refuse("the payout's address is not an address, so the transfer cannot be checked") unless address?(p[:address])
+      refuse("the payout's amount is not base units, so the transfer cannot be checked") unless decimal?(p[:amount])
+
+      { id: p[:id], destination_id: p[:destination_id], chain_id: Integer(p[:chain_id].to_s, 10),
+        token: p[:token], address: p[:address], amount: Integer(p[:amount].to_s, 10) }
+    end
+
+    private_class_method :parse, :payout_fields
+
+    # The payout must be FOR the destination the merchant registered: the gateway answers
+    # both, but the destination is the record the merchant typed and confirmed, so a payout
+    # that disagrees with it is one stitched from somewhere else.
+    def self.check_destination(pay, destination)
+      refuse("the destination is not a record") unless destination.is_a?(Hash)
+      d = symbolize(destination)
+      check_destination_id(pay[:destination_id], d[:id])
+      unless decimal?(d[:chain_id]) && Integer(d[:chain_id].to_s, 10) == pay[:chain_id]
+        refuse("the payout is on chain #{pay[:chain_id]} but the destination is on chain #{d[:chain_id].inspect}")
+      end
+      unless same_address?(d[:token], pay[:token])
+        refuse("the payout moves token #{pay[:token]} but the destination is for #{d[:token].inspect}")
+      end
+      return if same_address?(d[:address], pay[:address])
+
+      refuse("the payout pays #{pay[:address]} but the destination's address is #{d[:address].inspect}")
+    end
+
+    def self.check_destination_id(got, want)
+      return if blank?(got) || blank?(want) || got.to_s == want.to_s
+
+      refuse("the payout is for destination #{got} but you asked for #{want}")
+    end
+
+    # The caller's own amount, scaled locally, against the payout's base-unit amount. "all"
+    # and nil leave the amount to the gateway (the balance after the reserve, or the proof).
+    def self.check_amount(payout_units, amount, decimals)
+      return if blank?(amount) || amount.to_s.strip.casecmp("all").zero?
+
+      if decimals.nil?
+        refuse("the token's decimals are unknown, so the payout amount #{amount.to_s.inspect} cannot be checked")
+      end
+      want = Integer(TxVerify.to_base_units(amount.to_s, Integer(decimals)), 10)
+      return if want == payout_units
+
+      refuse("the payout moves #{payout_units} base units but you asked for #{want}")
+    end
+
+    private_class_method :check_destination, :check_destination_id, :check_amount
+
+    # Checks 2-5: the fields outside the calldata.
+    def self.check_header(fields, pay, signer)
+      unless TxVerify.zero_native_value?(fields["value"])
+        refuse("transaction attaches native currency (value=#{fields['value'].inspect}); an ERC-20 transfer is value-0")
+      end
+      unless decimal?(fields["chain_id"]) && Integer(fields["chain_id"].to_s, 10) == pay[:chain_id]
+        refuse("transaction targets chain #{fields['chain_id'].inspect} but this payout is on chain #{pay[:chain_id]}")
+      end
+      from = fields["from"].to_s
+      if signer && !from.empty? && !same_address?(from, signer)
+        refuse("transaction is prepared from #{from} but the signing key is #{signer}")
+      end
+
+      to = fields["to"].to_s.strip
+      refuse("the transaction has no `to` address; signing it would deploy a contract") if to.empty?
+      refuse("the transaction's `to` #{to.inspect} is not an address") unless address?(to)
+      return if same_address?(to, pay[:token])
+
+      refuse("transaction is addressed to #{to} but this payout's token is #{pay[:token]}")
+    end
+
+    # Check 6: the calldata, decoded word by word so the refusal names what differs, then
+    # its length — a transfer is exactly selector + two words, and anything appended is
+    # refused rather than ignored (the token would ignore it; the signature would not).
+    def self.check_call(data, address, units)
+      raw = data.to_s.strip.downcase.delete_prefix("0x")
+      refuse("calldata is not hex") unless raw.match?(/\A\h*\z/)
+      refuse("calldata is #{raw.length} hex chars, too short to carry a function selector") if raw.length < 8
+      selector = raw[0, 8]
+      unless selector == TRANSFER_SELECTOR
+        refuse("the call is selector 0x#{selector}, not #{TRANSFER_SIGNATURE} (0x#{TRANSFER_SELECTOR})")
+      end
+      want_len = 8 + (2 * WORD_HEX)
+      refuse("calldata is #{raw.length} hex chars, too short for #{TRANSFER_SIGNATURE}") if raw.length < want_len
+
+      recipient = raw[8, WORD_HEX]
+      want_recipient = address.downcase.delete_prefix("0x").rjust(WORD_HEX, "0")
+      unless recipient == want_recipient
+        refuse("the transfer pays 0x#{recipient[-40..]} but the payout destination is #{address}")
+      end
+      got_units = raw[8 + WORD_HEX, WORD_HEX].to_i(16)
+      refuse("the transfer moves #{got_units} base units but the payout is for #{units}") unless got_units == units
+      return if raw.length == want_len
+
+      refuse("calldata carries #{(raw.length - want_len) / 2} trailing bytes after #{TRANSFER_SIGNATURE}")
+    end
+
+    private_class_method :check_header, :check_call
+
+    def self.refuse(message)
+      raise TxVerify::RefusedSignature, "refusing to sign: #{message}"
+    end
+
+    def self.symbolize(hash)
+      hash.transform_keys { |k| k.respond_to?(:to_sym) ? k.to_sym : k }
+    end
+
+    def self.blank?(value)
+      value.nil? || value.to_s.strip.empty?
+    end
+
+    def self.decimal?(value)
+      value.is_a?(Integer) ? value >= 0 : value.is_a?(String) && value.match?(/\A\d+\z/)
+    end
+
+    def self.address?(value)
+      TxVerify.address?(value)
+    end
+
+    def self.same_address?(left, right)
+      address?(left) && address?(right) && left.casecmp(right).zero?
+    end
+
+    private_class_method :refuse, :symbolize, :blank?, :decimal?, :address?, :same_address?
+  end
+end

data/lib/rail0/request.rb

@@ -143,6 +143,7 @@ module Rail0
     end
 
     def page_meta(response)
+      links = page_links(response["link"])
       {
         page:        response["x-page"].to_i,
         per_page:    response["x-per-page"].to_i,
@@ -150,10 +151,27 @@ module Rail0
         # 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"])
+        links:       links,
+        next_cursor: next_cursor(response["x-next-cursor"], links[:next])
       }.freeze
     end
 
+    # The cursor of the next page on a cursor-paged list (the +after:+ of payments.list
+    # and payouts.list): the x-next-cursor header, or — should a proxy have dropped it —
+    # the +after+ query parameter of the Link +next+. nil on the last page, and on an
+    # offset-paged response (whose +next+ carries +page=+, not +after=+).
+    def next_cursor(header, next_link)
+      cursor = header.to_s.strip
+      return cursor unless cursor.empty?
+      return nil if next_link.nil?
+
+      query = next_link.split("?", 2)[1]
+      return nil if query.nil?
+
+      value = URI.decode_www_form(query).assoc("after")&.last
+      value.nil? || value.empty? ? nil : value
+    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".