# request

The main method for interacting with Stacks and Bitcoin wallets via JSON-RPC. This method handles automatic error handling, request parameter serialization, wallet selection UI, and optional local storage caching.

For more advanced or low-level use cases, consider using the [`requestRaw`](https://docs.stacks.co/reference/stacks.js/stacks-connect/request/requestraw) method directly.

***

### Usage

```ts
import { request } from '@stacks/connect';

// Simple usage with just a method and params
const result = await request('stx_transferStx', {
  recipient: 'SP2...address',
  amount: 1000000n,
  memo: 'Payment',
});
```

```ts
import { request } from '@stacks/connect';

// Usage with ConnectRequestOptions
const result = await request(
  {
    forceWalletSelect: true,
    persistWalletSelect: true,
    enableOverrides: true,
    enableLocalStorage: true,
  },
  'stx_transferStx',
  {
    recipient: 'SP2...address',
    amount: 1000000n,
    memo: 'Payment',
  }
);
```

```ts
import { request } from '@stacks/connect';

// Send BTC
const result = await request('sendTransfer', {
  recipients: [
    {
      address: 'bc1q...address',
      amount: 100_000_000n, // 1 BTC = 100,000,000 sats
    },
  ],
});
```

#### Notes

* When no `provider` is specified and no wallet has been previously selected, the wallet selection modal is automatically displayed.
* Parameters containing `bigint` values and Clarity values are automatically serialized before being sent to the wallet.
* Post conditions are automatically serialized to hex strings.
* If `enableLocalStorage` is `true` (the default), address results from `getAddresses` calls are cached in local storage.
* In SSR (server-side rendering) contexts, the method returns `undefined` instead of throwing an error.
* Pressing `Escape` while the wallet modal is open will cancel the request and throw a `JsonRpcError` with code `UserCanceled`.

[**Reference Link**](https://github.com/stx-labs/connect/blob/main/packages/connect/src/request.ts#L168)

***

### Signature

The `request` function supports two call signatures via overloads:

```ts
// Overload 1: Method and params only
function request<M extends keyof Methods>(
  method: M,
  params?: MethodParams<M>
): Promise<MethodResult<M>>;

// Overload 2: With ConnectRequestOptions
function request<M extends keyof Methods>(
  options: ConnectRequestOptions,
  method: M,
  params?: MethodParams<M>
): Promise<MethodResult<M>>;
```

***

### Returns

`Promise<MethodResult<M>>`

The return type depends on the wallet method being called. Each wallet method defines its own result type. See individual method reference pages for specific return types.

| Method                      | Result Type                                                                                                        |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `getAddresses`              | [`GetAddressesResult`](https://docs.stacks.co/reference/stacks.js/stacks-connect/methods/getaddresses)             |
| `sendTransfer`              | [`TxidResult`](https://docs.stacks.co/reference/stacks.js/stacks-connect/methods/sendtransfer)                     |
| `signPsbt`                  | [`SignPsbtResult`](https://docs.stacks.co/reference/stacks.js/stacks-connect/methods/signpsbt)                     |
| `stx_transferStx`           | [`TransactionResult`](https://docs.stacks.co/reference/stacks.js/stacks-connect/methods/stx_transferstx)           |
| `stx_callContract`          | [`TransactionResult`](https://docs.stacks.co/reference/stacks.js/stacks-connect/methods/stx_callcontract)          |
| `stx_deployContract`        | [`TransactionResult`](https://docs.stacks.co/reference/stacks.js/stacks-connect/methods/stx_deploycontract)        |
| `stx_signTransaction`       | [`SignTransactionResult`](https://docs.stacks.co/reference/stacks.js/stacks-connect/methods/stx_signtransaction)   |
| `stx_signMessage`           | [`SignMessageResult`](https://docs.stacks.co/reference/stacks.js/stacks-connect/methods/stx_signmessage)           |
| `stx_signStructuredMessage` | [`SignMessageResult`](https://docs.stacks.co/reference/stacks.js/stacks-connect/methods/stx_signstructuredmessage) |
| `stx_getAddresses`          | [`GetAddressesResult`](https://docs.stacks.co/reference/stacks.js/stacks-connect/methods/stx_getaddresses)         |
| `stx_getAccounts`           | [`GetAccountsResult`](https://docs.stacks.co/reference/stacks.js/stacks-connect/methods/stx_getaccounts)           |
| `stx_updateProfile`         | [`UpdateProfileResult`](https://docs.stacks.co/reference/stacks.js/stacks-connect/methods/stx_updateprofile)       |
| `stx_transferSip10Ft`       | [`TransactionResult`](https://docs.stacks.co/reference/stacks.js/stacks-connect/methods/stx_transfersip10ft)       |
| `stx_transferSip9Nft`       | [`TransactionResult`](https://docs.stacks.co/reference/stacks.js/stacks-connect/methods/stx_transfersip9nft)       |

***

### Parameters

#### method (required)

* **Type**: `keyof Methods`

The wallet JSON-RPC method name to call. See the table above for all available methods.

#### params (optional)

* **Type**: `MethodParams<M>`

The parameters object for the specified method. Each method defines its own parameter type. See individual method reference pages for details.

#### options (optional)

* **Type**: [`ConnectRequestOptions`](https://docs.stacks.co/reference/stacks.js/stacks-connect/request/connectrequestoptions)

Configuration options for the request, including provider selection, wallet UI behavior, and local storage settings. See the [`ConnectRequestOptions`](https://docs.stacks.co/reference/stacks.js/stacks-connect/request/connectrequestoptions) reference for full details.

***

### Error Handling

The `request` method throws a [`JsonRpcError`](https://docs.stacks.co/reference/stacks.js/stacks-connect/errors/jsonrpcerror) when the wallet returns an error or the user cancels the request. You should wrap calls in a `try/catch` block:

```ts
import { request } from '@stacks/connect';
import { JsonRpcError } from '@stacks/connect';

try {
  const result = await request('stx_transferStx', {
    recipient: 'SP2...address',
    amount: 1000000n,
  });
  console.log('Transaction ID:', result.txid);
} catch (error) {
  if (error instanceof JsonRpcError) {
    console.error('Wallet error:', error.code, error.message);
  }
}
```

***

### Provider Override Behavior

When `enableOverrides` is `true` (the default), `request` automatically adjusts method names and parameter formats for different wallet providers (e.g. Xverse, Leather, Fordefi) to normalize behavior across the ecosystem. This includes:

* Converting `getAddresses` to `wallet_connect` for Xverse-like wallets.
* Normalizing `amount` types between `number` and `string` depending on the wallet.
* Transforming `signPsbt` input formats to match each wallet's expected schema.
* Normalizing response fields like `txId` vs `txid` and `hex` vs `psbt`.