> For the complete documentation index, see [llms.txt](https://docs.stacks.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.stacks.co/reference/stacks.js/stacks-bitcoin-staking/build/buildgrantsignerkey.md).

# buildGrantSignerKey

Builds an unsigned contract call to pox-5 `grant-signer-key`, which records that a signer key authorizes a signer-manager to register it. The authorization is a SIP-018 signature from the signer key over the signer-manager and an `authId`.

{% hint style="warning" %}
Sent from a wallet, this transaction fails with `ERR_UNAUTHORIZED_SIGNER_REGISTRATION (u26)` for a signer-manager contract. pox-5 requires `contract-caller` to be the signer-manager. See Notes.
{% endhint %}

***

### Usage

```ts
import {
  buildGrantSignerKey,
  fetchEligibleGrantSignerKey,
  signSignerGrant,
} from '@stacks/bitcoin-staking';
import { STACKS_MAINNET } from '@stacks/network';
import {
  fetchNonce,
  privateKeyToAddress,
  privateKeyToPublic,
  publicKeyToHex,
} from '@stacks/transactions';

const network = 'mainnet';
const signerPrivateKey = process.env.SIGNER_KEY!;
const signerKey = publicKeyToHex(privateKeyToPublic(signerPrivateKey));
const signerManager = 'SP2C2YFP12AJZB4MABJBAJ55XECVS7E4PMMZ89YZR.my-signer-manager';
const authId = 1n;

const signerSignature = signSignerGrant({
  signerManager,
  authId,
  chainId: STACKS_MAINNET.chainId,
  privateKey: signerPrivateKey,
});

const check = await fetchEligibleGrantSignerKey({ signerKey, signerManager, authId, signerSignature, network });
if (!check.ok) throw new Error(`grant-signer-key would fail: ${check.reasons}`);

// contract-caller must equal signerManager: see Notes.
const senderKey = process.env.SENDER_KEY!;
const tx = await buildGrantSignerKey({
  signerKey,
  signerManager,
  authId,
  signerSignature,
  publicKey: publicKeyToHex(privateKeyToPublic(senderKey)),
  fee: 10_000n, // micro-STX
  nonce: await fetchNonce({ address: privateKeyToAddress(senderKey, network), network }),
  network,
});
```

#### Notes

* pox-5 requires `contract-caller` to equal `signerManager` and fails with `ERR_UNAUTHORIZED_SIGNER_REGISTRATION (u26)` otherwise ([pox-5.clar L2743-L2811](https://github.com/stacks-network/stacks-core/blob/10474cdec9f9c0bdf05841b58cffc89cdad87a9b/stackslib/src/chainstate/stacks/boot/pox-5.clar#L2743-L2811)). This builder calls pox-5 directly, so `contract-caller` is the transaction's origin account. With a signer-manager contract as `signerManager`, the call fails with u26: the signer-manager contract has to submit the grant itself. [signSignerGrant](/reference/stacks.js/stacks-bitcoin-staking/signer/signsignergrant.md) and [verifySignerGrant](/reference/stacks.js/stacks-bitcoin-staking/signer/verifysignergrant.md) produce and check the signature it forwards. See [Deploy a signer-manager contract](https://docs.stacks.co/operate/deploy-a-signer-manager-contract).
* Each `(signerKey, signerManager, authId)` can be granted once (`ERR_SIGNER_KEY_GRANT_USED (u12)`). Check with [fetchSignerKeyGrantUsed](/reference/stacks.js/stacks-bitcoin-staking/fetch/fetchsignerkeygrantused.md).
* pox-5 recovers a public key from `signerSignature` over the grant hash and compares it with `signerKey`. An unrecoverable signature fails with `ERR_INVALID_SIGNATURE_RECOVER (u13)`, a different key with `ERR_INVALID_SIGNATURE_PUBKEY (u14)`. The hash includes the chain ID pox-5 runs on, so sign with the target network's `chainId`.
* [fetchEligibleGrantSignerKey](/reference/stacks.js/stacks-bitcoin-staking/eligibility/fetcheligiblegrantsignerkey.md) dry-runs the replay and signature checks. It does not run the caller check.
* On success, pox-5 marks the `authId` used and sets the grant for `(signerKey, signerManager)`. `register-signer` and every staking entry point require that grant. Remove it with [buildRevokeSignerGrant](/reference/stacks.js/stacks-bitcoin-staking/build/buildrevokesignergrant.md).
* No asset moves, so the call needs no post conditions.
* A txid from [broadcastTransaction](/reference/stacks.js/stacks-transactions/network/broadcasttransaction.md) confirms submission only. The call can still fail on-chain: read the mined transaction's result and pass an `(err uN)` to [parsePox5Error](/reference/stacks.js/stacks-bitcoin-staking/errors/parsepox5error.md).

[**Reference Link**](https://github.com/stx-labs/stacks.js/blob/6101c99efe5a9616ce7e16cef68e28fd10676e7e/packages/bitcoin-staking/src/build.ts#L779-L825)

***

### Signature

```ts
function buildGrantSignerKey(args: BuildGrantSignerKeyTxArgs): Promise<StacksTransactionWire>;
```

`args` is a [BuildGrantSignerKeyTxArgs](/reference/stacks.js/stacks-bitcoin-staking/types/buildgrantsignerkeytxargs.md), which includes [TxParams](/reference/stacks.js/stacks-bitcoin-staking/types/txparams.md).

***

### Returns

`Promise<StacksTransactionWire>`

Resolves to an unsigned [StacksTransactionWire](/reference/stacks.js/stacks-transactions/signing/stackstransactionwire.md) that calls pox-5 `grant-signer-key`. Sign it with [TransactionSigner](/reference/stacks.js/stacks-transactions/signing/transactionsigner.md), then send it with [broadcastTransaction](/reference/stacks.js/stacks-transactions/network/broadcasttransaction.md).

***

### Parameters

#### args.signerKey (required)

* **Type**: `Uint8Array | string`

Compressed secp256k1 public key of the signer, 33 bytes, as bytes or hex.

#### args.signerManager (required)

* **Type**: `string`

Stacks principal of the signer-manager being authorized.

#### args.authId (required)

* **Type**: `IntegerType`

Replay nonce. It must be the value the signer signed.

#### args.signerSignature (required)

* **Type**: `Uint8Array | string`

65-byte recoverable signature in RSV order, as bytes or hex, from [signSignerGrant](/reference/stacks.js/stacks-bitcoin-staking/signer/signsignergrant.md).

#### args.fee (required)

* **Type**: `IntegerType`

Transaction fee in micro-STX.

#### args.nonce (required)

* **Type**: `IntegerType`

Nonce of the origin account. Read it with [fetchNonce](/reference/stacks.js/stacks-transactions/network/fetchnonce.md).

#### args.network (required)

* **Type**: `StacksNetworkName | StacksNetwork`

A name such as `'mainnet'` or `'testnet'`, or a [StacksNetwork](/reference/stacks.js/stacks-network/network/stacksnetwork.md) object. Sets the contract address (the network's boot address, `SP000000000000000000002Q6VF78` on mainnet) and the transaction version and chain ID.

#### args.publicKey (required for a single-sig origin)

* **Type**: `string`

Hex public key of the account that signs the transaction.

#### args.publicKeys and args.numSignatures (required for a multisig origin)

* **Type**: `PublicKey[]` and `number`

Pass these instead of `publicKey` to build for an M-of-N multisig origin. This package defaults `useNonSequentialMultiSig` to `true`; pass `false` for the sequential hash mode. Pass `address` to check the key order against the multisig address.

#### args.postConditions (optional)

* **Type**: `PostCondition[]`

[Post conditions](/reference/stacks.js/stacks-transactions/types/postcondition.md) to attach. The builder adds none.

#### args.postConditionMode (optional)

* **Type**: `PostConditionModeName`

`'allow'`, `'deny'` or `'originator'`. Defaults to `'deny'`.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.stacks.co/reference/stacks.js/stacks-bitcoin-staking/build/buildgrantsignerkey.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.