> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chipipay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API reference

> ChipiConnector options, window registration, passive calls, errors, the Wallet Standard wallet and compatibility.

## Options

```ts theme={null}
import { ChipiConnector } from "@chipi-stack/starknet-connector";

new ChipiConnector({
  walletUrl: "https://wallet.chipipay.com", // hosted wallet base URL (default)
  id: "chipi", // connector id (default); the window key stays starknet_chipi
  name: "Connect with Chipi", // display name (default)
  icon: "data:image/png;base64,...", // default: a 48x48 PNG data URI
  register: true, // put window.starknet_chipi on the page (default; no-op in SSR)
  transport: {
    windowName: "chipi-wallet", // default: a new random name per open
    windowFeatures: "popup=yes,width=420,height=680", // default
    openTimeoutMs: 180_000, // wait for the wallet page to load (default)
    requestTimeoutMs: 120_000, // per request; 0 disables (default)
  },
});
```

`chipi(options)` is the same as `new ChipiConnector(options)`.

| Method | Behavior |
| - | - |
| `available()` | Always `true`: there is no extension to detect. |
| `ready()` | `true` only after `connect()` succeeded on this page. There is no silent reconnect. |
| `connect()` | Opens the popup and requests the account. Call it from a click. |
| `disconnect()` | Closes the popup, rejects waiting requests and removes `window.starknet_chipi`. |
| `account(provider)` | A starknet.js `WalletAccount` over the popup channel. Throws `chipi_not_connected` before `connect()`. |
| `chainId()` | Always `SN_MAIN`. |

## Window registration

Creating a `ChipiConnector` puts a get-starknet wallet object on `window.starknet_chipi` (id
`"chipi"`) and dispatches a `starknet:announceWallet` event, again on each
`starknet:requestWallets`. Code that scans `window.starknet*` (get-starknet v4,
get-starknet-discovery's injected scan) then finds Chipi without importing this package.

* Nothing is registered by installing the package, only by creating a connector.
* `register: false` opts out. It is a no-op during SSR.
* `disconnect()` removes the object; the next `connect()` adds a new one.
* The connector never writes `window.starknet`. It replaces whatever is on
  `window.starknet_chipi` while it is registered, and on removal deletes only its own object.

## Passive calls

While no wallet window is open (before `connect()`, or after the user closed it), the connector
answers these calls itself and does not open the popup. Wallet scanners send them at page load.
Once the window is open, they go to the wallet.

| Call | Answer with no wallet window open |
| - | - |
| `wallet_getPermissions` | `[]` |
| `wallet_requestAccounts` with `silent_mode: true` | `[]` |
| `wallet_requestChainId` | `"0x534e5f4d41494e"` (`SN_MAIN`) |

`wallet_requestAccounts` without `silent_mode: true` opens the popup, so send it from a click.
Since 0.5.0; before that, these calls tried to open the popup outside a click, which the browser
blocked.

## Events

* Account and network changes in the wallet reach the dApp as starknet-react `change` events
  (`{ account, chainId }`). An empty account list (wallet locked or signed out) is a
  `disconnect`.

## Errors

The connector rejects with an `Error`. Check `err.code` first, then `err.message`.

| `code` or message | When |
| - | - |
| code `"UNSUPPORTED_CHAIN"` | `connect({ chainIdHint })` with a chain other than `SN_MAIN`. No popup opens. |
| code `"popup_blocked"` | The browser blocked the popup: `connect()` did not run from a click. |
| message `"wallet_open_timeout"` | The wallet page did not load within `transport.openTimeoutMs` (180 s). The popup closes. |
| code `"REQUEST_TIMEOUT"` | No answer within `transport.requestTimeoutMs` (120 s). |
| code `"POPUP_CLOSED"` | A request after the user closed the wallet window. Call `connect()` again from a click. |
| code `4001`, message `"User closed the wallet"` | The user closed the wallet window while a request was waiting. |
| code `4001`, message `"disconnected"` | `disconnect()` ran while a request, or the wallet page load, was waiting. |
| message `"chipi_no_account"` | The wallet returned no account on connect. |
| message `"chipi_not_connected"` | `account()` before `connect()`. |
| message `"chipi_connector_requires_browser"` | The popup was requested without `window` (SSR). |
| numeric code from the wallet | The wallet's own error, passed through as `err.code` with its message. |

The wallet's numeric codes are listed in [Security model](/sdk/connector/security#error-codes-of-the-chipi-wallet-object):
`113`, `114`, `115`, `116` and `163`.

## Requests in flight

Each request is posted to the wallet right away and matched to its answer by id. Several can be
in flight at once: the connector neither queues nor rejects them. If the wallet page reloads
(for example after sign-in) and announces itself again, unanswered requests are sent again with
the same id. Serialize prompts in your dApp anyway; Bramble, for one, allows 5 pending prompts
per site.

## Wallet Standard

get-starknet v5 and v6 (`@starknet-io/get-starknet-discovery`) and other Wallet Standard apps
discover wallets through `wallet-standard:register-wallet`. Register Chipi once, on the client:

```ts theme={null}
import { registerChipiStandardWallet } from "@chipi-stack/starknet-connector";

const unregister = registerChipiStandardWallet();
```

The wallet exposes `starknet:walletApi`, `standard:connect`, `standard:disconnect` and
`standard:events` on chain `starknet:0x534e5f4d41494e` (mainnet), backed by the same popup.
`connect({ silent: true })` never opens the popup. `createChipiStandardWallet()` returns the
wallet without registering it. Its default name is `"Chipi"`; the connector's is
`"Connect with Chipi"`.

How get-starknet-discovery (5.0.0 and 6.0.6, same code) builds its list in `createStore()`:

* Wallet Standard wallets are added whenever they register.
* `window.starknet*` objects are scanned **once**, when `createStore()` runs, and wrapped as
  injected wallets. Entries are de-duplicated by **name**, and a Wallet Standard entry wins.

So Bramble, which has no Wallet Standard registration, is listed only if
`window.starknet_bramble` exists when `createStore()` runs. And if a page creates both a
`ChipiConnector` and the Wallet Standard wallet before the store, it lists two Chipi entries
(`"Chipi"` and `"Connect with Chipi"`): pass `register: false` to the connector, or give both
the same `name`.

## Compatibility and limits

* `@starknet-react/core` >= 3 (peer), tested against 5.0.3. `starknet` >= 8.1.2 (peer). The
  Wallet Standard wallet needs neither.
* **Starknet mainnet** only.
* **Popup only** (external dApps). An in-app-browser ("parent") mode is in the transport but not
  exposed.

## Package

| | |
| - | - |
| npm | [`@chipi-stack/starknet-connector`](https://www.npmjs.com/package/@chipi-stack/starknet-connector) |
| Example | [`chipi-pay/build-with-chipi` → Tutorial 03](https://github.com/chipi-pay/build-with-chipi/tree/main/tutorials/03-connect-with-chipi) |
| Versioning | Independent, not part of the fixed `@chipi-stack/*` changeset group |

> ✅ Verified against the SDK source on **2026-10-12**.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.