# API Reference

Every function, method, constant and type in @joeywallet/wallet-sdk.

## Detection

All exported from `@joeywallet/wallet-sdk`. Detection only reads the page; it never messages the extension.

### `getJoey(): Joey | null`

Returns the Joey client, or `null` if the extension isn't present. Synchronous, never throws, and returns the same client object each time.

### `isJoeyAvailable(): boolean`

`true` when `getJoey()` would return a client.

### `requireJoey(): Joey`

Like `getJoey()`, but throws `JoeyRpcError` 4900 instead of returning `null`.

### `waitForJoey(options?): Promise<Joey>`

```ts
interface WaitForJoeyOptions {
  timeoutMs?: number // default 3000
  signal?: AbortSignal
}
```

Resolves immediately if Joey is present; otherwise waits for the extension to announce itself. It rejects with 4900 if the timeout passes (or on the server), and with -32603 if `signal` aborts.

### Other detection helpers

| Function | Description |
|---|---|
| `resetJoeyDetection()` | Clears the cached client. Only needed in tests or apps that swap providers. |
| `createJoeyClient(provider)` | Wraps a raw injected provider in the typed client. `getJoey()` does this for you. |
| `isJoeyInjectedProvider(value)` | Type guard for a raw provider object. |

## The `Joey` client

Returned by `getJoey()`, `waitForJoey()` and `requireJoey()`. Every async method resolves with its result or rejects with a [`JoeyRpcError`](/docs/browser-extension/errors).

### Properties

| Member | Type | Description |
|---|---|---|
| `accounts` | `readonly string[]` | Granted addresses; empty until connected |
| `chain` | `JoeyChain \| null` | Current chain, or `null` before connecting |
| `capabilities` | `readonly string[]` | Optional features, such as `['batch']` (SDK 0.5.0+) |
| `version` | `string \| undefined` | Version of the injected provider interface (not the extension version) |
| `rdns` | `string \| undefined` | `'xyz.joeywallet'` |
| `provider` | `JoeyInjectedProvider` | The raw injected provider |
| `isConnected()` | `boolean` | Whether your site currently holds a grant |
| `supportsBatch()` | `boolean` | Whether Joey will sign XLS-56 `Batch` transactions (SDK 0.5.0+) |

### `connect(params?)`

```ts
interface ConnectParams { chain?: JoeyChain; silent?: boolean; name?: string; icon?: string }
interface ConnectResult { accounts: JoeyAccount[]; chain: JoeyChain | null; networkId: number | null }
interface JoeyAccount { address: string; publicKey?: string; label?: string }
```

- **Already approved:** returns the existing grant immediately, without a prompt.
- **`silent: true`:** never prompts. Returns `{ accounts: [] }` if your site isn't approved, and works while Joey is locked.
- **Otherwise:** opens the approval window, where the user chooses which accounts to share. If Joey is locked, the request waits behind the unlock screen.
- `name` (up to 128 characters) and `icon` (an `https:` or `data:image/` URL) are validated, but the approval screen shows your site's verified origin rather than these values.
- **Errors:** `4001` rejected or expired; `-32602` invalid params; `-32005` rate limited.

### `disconnect(): Promise<void>`

Revokes your site's grant and withdraws its pending requests. Other tabs and frames of your origin receive a `disconnect` event.

### `getAccounts(): Promise<string[]>`

Granted addresses, or `[]` if your site isn't connected. Never throws for an unconnected site.

### `getNetwork(): Promise<JoeyNetwork>`

```ts
interface JoeyNetwork { chain: JoeyChain; networkId: number; name: string } // 'Mainnet' | 'Testnet' | 'Devnet'
```

Requires a connected site; otherwise rejects with `4100`.

### `signTransaction(params)`

Signs without submitting.

```ts
interface SignTransactionParams<TTx> {
  tx_json: TTx
  account?: string    // which granted address signs; defaults to the first
  chain?: JoeyChain   // refuse with 4901 if Joey is on another network
  autofill?: boolean  // default true: fills Fee, Sequence, LastLedgerSequence
}
interface SignTransactionResult { tx_json: Record<string, unknown>; tx_blob: string; hash: string }
```

The returned `tx_json` is decoded from the signed blob, so it includes the filled fields, `SigningPubKey` and `TxnSignature`.

### `signAndSubmitTransaction(params)`

Same parameters as `signTransaction`. One approval covers signing and submitting.

```ts
interface SignAndSubmitTransactionResult extends SignTransactionResult {
  engine_result?: string         // preliminary, e.g. 'tesSUCCESS'
  engine_result_message?: string
  batch?: BatchSubmitOutcome     // present for XLS-56 Batch transactions (0.5.0+)
}
```

### `signTransactionFor(params)`

Adds one multisignature for a granted account.

```ts
interface SignTransactionForParams<TTx> {
  tx_signer: string // a granted address; otherwise 4100
  tx_json: TTx      // Account is the multisigned account
  account?: string
  chain?: JoeyChain
}
```

This method **never autofills**: set `Fee`, `Sequence` and `LastLedgerSequence` yourself so every signer signs identical bytes. The multisign fee is `base fee × (1 + number of signatures)`.

### `signTransactionBulk(params)`

Signs, and optionally submits, up to 32 transactions with one approval.

```ts
interface SignTransactionBulkParams<TTx> {
  tx_list: Array<{ tx_json: TTx }> // at most 32 (MAX_BULK_TRANSACTIONS)
  submit: boolean                  // required
  autofill?: boolean
  account?: string
  chain?: JoeyChain
}
// resolves with SignAndSubmitTransactionResult[]
```

Bulk submission is **not atomic**. See [Batch and bulk](/docs/browser-extension/batch-and-bulk) for ordering and partial failures.

### `signIn(params?)`

Proves the user controls an address. See [Sign-in](/docs/browser-extension/sign-in).

### `on(event, listener)` and `off(event, listener)`

Subscribe to `connect`, `disconnect`, `accountsChanged` and `networkChanged`. `on()` returns an unsubscribe function. See [Events](/docs/browser-extension/events).

### `request({ method, params })`

A low-level escape hatch for wallet methods newer than your SDK version. Errors are still `JoeyRpcError`.

## Method summary

| Method | Needs a connection | Needs Joey unlocked | Prompts the user |
|---|---|---|---|
| `connect` | No | Yes, except `silent` (waits for unlock) | Unless already approved or `silent` |
| `disconnect` | No | No | No |
| `getAccounts` | No | No | No |
| `getNetwork` | Yes | No | No |
| `signTransaction`, `signAndSubmitTransaction`, `signTransactionFor`, `signTransactionBulk`, `signIn` | Yes | Yes (waits for unlock) | Yes |

## Constants

| Export | Value |
|---|---|
| `JOEY_CHAINS` | `['xrpl:0', 'xrpl:1', 'xrpl:2']` |
| `JOEY_WALLET_NAME` | `'Joey'` |
| `JOEY_RDNS` | `'xyz.joeywallet'` |
| `REQUEST_TIMEOUT_MS` | `30000`: limit for calls that don't need approval |
| `APPROVAL_TIMEOUT_MS` | `300000`: limit for calls that wait on the user |
| `MAX_BULK_TRANSACTIONS` | `32` |
| `JOEY_ERROR_CODES` | See [Errors](/docs/browser-extension/errors) |
| `JOEY_RPC_METHODS` | The wire method names: `connect`, `disconnect`, `getAccounts`, `getNetwork`, `signTransaction`, `signAndSubmitTransaction`, `signTransactionFor`, `signTransactionBulk`, `signIn` |
| `JOEY_CAPABILITIES` | `{ batch: 'batch' }` (0.5.0+) |
| `BATCH_FLAGS` | `tfAllOrNothing`, `tfOnlyOne`, `tfUntilFailure`, `tfIndependent` (0.5.0+) |
| `TF_INNER_BATCH_TXN` | `0x40000000` (0.5.0+) |
| `CAIP294_ANNOUNCE_EVENT`, `CAIP294_PROMPT_EVENT` | `'wallet_announce'`, `'wallet_prompt'` |
| `WALLET_STANDARD_REGISTER_EVENT`, `WALLET_STANDARD_APP_READY_EVENT` | `'wallet-standard:register-wallet'`, `'wallet-standard:app-ready'` |

`JOEY_DAPP_FORBIDDEN_TRANSACTION_TYPES` is deprecated and empty. Don't use it to decide what Joey will sign; handle the wallet's error instead.

## Helpers

| Function | Description |
|---|---|
| `isJoeyChain(value)` | Type guard for `xrpl:0`, `xrpl:1` or `xrpl:2` |
| `chainForNetworkId(id)` | `0` → `'xrpl:0'`; throws `RangeError` for unknown IDs |
| `networkIdForChain(chain)` | `'xrpl:1'` → `1`, otherwise `null` |
| `isChallengeSignIn(result)` | Narrows a sign-in result to the Ledger challenge shape |
| `hasCapability(provider, capability)` | Checks a raw provider's capabilities (0.5.0+) |
| `isUserRejection(error)` | `true` when the user declined |
| `userRejectedError(message?)`, `notInstalledError()` | Build errors with the matching codes |

### Low-level helpers

Most apps don't need these; the `Joey` client uses them internally.

| Function | Description |
|---|---|
| `invoke(provider, method, params)` | Call a raw provider method, preferring a typed method and falling back to `request()` |
| `subscribe(provider, event, listener)` | Subscribe on a raw provider; returns an unsubscribe function |
| `readAccounts`, `readChain`, `readNetwork` | Normalise raw provider payloads |
| `initialMutationState`, `mutationReducer`, `toPublicState` | The framework-free state machine behind the React mutation hooks, for building bindings for other frameworks |

## Types

The package exports types for everything above:

- **Transactions:** `TransactionLike`, `AnyTransaction`, `Amount`, `IssuedCurrencyAmount`, `MPTAmount`, `Memo`, `Signer`, `Path`, `PathStep`
- **Connection and network:** `ConnectParams`, `ConnectResult`, `JoeyAccount`, `JoeyChain`, `JoeyNetwork`, `JoeyCapability`
- **Signing:** `SigningContextParams`, `SignTransactionParams`, `SignTransactionResult`, `SignAndSubmitTransactionResult`, `SignTransactionForParams`, `SignTransactionBulkParams`, `SignTransactionBulkFailure`, `BulkEntryResult`, `BulkEntryStatus`
- **Batch:** `BatchTransaction`, `BatchInnerTransaction`, `BatchSigner`, `BatchSubmitOutcome`
- **Sign-in:** `SignInParams`, `SignInMode`, `SignInResult`, `Caip122SignInResult`, `ChallengeSignInResult`
- **Events:** `JoeyEventMap`, `JoeyEventName`, `JoeyEventListener`
- **Provider and errors:** `JoeyInjectedProvider`, `JoeyRequestArguments`, `JoeyRpcMethod`, `JoeyProviderEventName`, `JoeyErrorCode`
- **React and vanilla:** `JoeyProviderProps`, `JoeyContextValue`, `UseJoeyMutationOptions`, `UseJoeyMutationResult`, `CreateJoeySessionOptions`, `JoeySessionState`, `BindConnectButtonOptions`
- **Mutation state:** `MutationState`, `MutationStatus`, `MutationAction`