Add network. Fund.
Connect.

// the problem

Onboarding is where Robinhood Chain dApps lose people

A visitor arrives with a wallet, without your network, and with nothing on it. Three things have to happen before your app can do anything, and each one has its own way of going wrong.

// the state machine

Every state is designed, and the type says so

OnboardingStatus is an exhaustive union. A switch over it with no default stops compiling the moment a state goes unhandled, so the states people actually hit first cannot be the ones that were skipped.

// evidence

The parameter object is the whole contract

Adding a network is one RPC call carrying one object. A zero-padded chainId, a currency symbol outside two to six characters, or a declared chain ID that disagrees with what the RPC answers, and MetaMask refuses. Silently, in every dApp that copied the snippet. Both objects ship exactly, and the test suite asserts them literally.

import { hoodMainnet } from 'hood-connect'

hoodMainnet.addChainParameter
// {
//   chainId: '0x1237',
//   chainName: 'Robinhood Chain',
//   nativeCurrency: {
//     name: 'Ether', symbol: 'ETH', decimals: 18
//   },
//   rpcUrls: [
//     'https://rpc.mainnet.chain.robinhood.com'
//   ],
//   blockExplorerUrls: [
//     'https://robinhoodchain.blockscout.com'
//   ],
// }

// surfaces

Four ways in, one machine underneath

The core is framework-agnostic and depends on nothing but viem's types. React, wagmi, and the custom element are thin layers over the same state machine and the same pure state-to-view projection, so they cannot drift apart.

import { HoodConnect } from 'hood-connect/react'

<HoodConnect
  config={{ chain: 'mainnet' }}
  theme="auto"
  onReady={(s) => console.log(s.address)}
/>

import { createHoodConfig }
  from 'hood-connect/wagmi'

export const config = createHoodConfig({
  networks: ['mainnet'],
  ssr: true,
})

<hood-connect chain="mainnet"></hood-connect>

el.addEventListener(
  'hood-connect:ready',
  (e) => console.log(e.detail.address)
)

import { createOnboarding }
  from 'hood-connect'

const o = createOnboarding()
o.subscribe(render)
o.start()

// step three

Funding routes, not a bridge contract

Robinhood Chain is an Arbitrum Orbit chain, so its canonical deposit path is the Arbitrum portal, not a contract this package could call. Nothing here moves funds, signs, or holds a key. The mainnet routes are the ones the chain's own bridging docs list.

The receive route ships on every network and under every configuration, because it is the only one that cannot break: anyone who can get ETH anywhere can send it to their own address. Its URI carries the chain ID, which is what keeps a scanned code off Ethereum mainnet. The testnet has no documented public bridge, so there receive is the only default and you supply your own routes rather than finding a broken link.

// failure handling

Wallet error codes, normalised once

Wallets disagree about how to report the same condition. Several wrap the real code in a generic -32603, and some only say it in prose. Every failure becomes one of a small closed set, each with a recovery hint written for a user and a retryable flag so the UI never offers a pointless button.

// quickstart

Three lines to a working flow

$ npm install hood-connect viem
$ npm install qrcode-generator   # optional, adds the QR to the funding step

import { HoodConnect } from 'hood-connect/react'

export function Page() {
  return <HoodConnect config={{ chain: 'mainnet' }} theme="auto" />
}

Node 20 or newer. viem is a peer dependency; react, wagmi, @wagmi/core, and qrcode-generator are optional peers, so the base install stays small. Full wiring for Next.js, wagmi, and a plain page is in INTEGRATION.md.