> ## Documentation Index
> Fetch the complete documentation index at: https://new-docs.squads.so/llms.txt
> Use this file to discover all available pages before exploring further.
# Transaction Builder
> Create custom transactions with arbitrary instructions from your Squad
The Transaction Builder lets you create custom transactions and populate them with arbitrary instructions, enabling direct interaction with any program on Solana from your Squad. Use it for operations that don't have a dedicated feature in the Squads app, such as interacting with custom Anchor programs, executing native Solana program instructions, or managing validators and stake pools.
## What you can do with it
Most things a Solana transaction can do, as long as the Squad vault (plus any ephemeral signers) signs. The Squads program itself cannot be called from the Transaction Builder. Some common uses:
| Use | Start from | What it involves |
| - | - | - |
| **Run admin instructions on your own program** | **Custom transaction**, **Anchor** tab | Load your program's IDL with **Load IDL** or **Import local IDL**, pick the instruction (for example, updating a config account or rotating an admin key), and fill in the accounts. The vault must be the program's admin signer. |
| **Call a program that has no IDL** | **Custom transaction**, **Solana** tab | Enter the program ID, each account with its **Signer**, **Writable**, or **Ephemeral** flags, and the instruction data. |
| **Approve a transaction built elsewhere** | **Import from base58 / base64** | Build the transaction with your own script or tool, with the Squad vault as the signer, then paste it. Legacy and versioned transactions are accepted, and their address lookup tables are added for you. |
| **Manage stake accounts** | **Stake program** template | Change a stake account's authority, delegate, split, merge, deactivate, or withdraw. **MoveStake** moves stake from an active stake account to another one, and **MoveLamports** moves excess lamports between stake accounts. The vault must be the stake account's authority. |
| **Operate a validator** | **Vote program** template | Change the withdraw authority, withdraw rewards, update the commission, or change the commission collectors of a vote account whose withdraw authority is the vault. The [Validators](/app-guide/developer-assets/validators) page offers the same actions with dedicated forms. |
| **Run a stake pool** | **Stake Pool program** template | Set the pool's staker or funding authority, change its manager (the new manager must also sign), and set its epoch, deposit, withdrawal, and referral fees. The vault must be the pool's manager. |
| **Move or clean up tokens** | **Token program** template | Transfer SPL tokens (not Token-2022), or close an empty token account the vault owns and send its rent to an address you choose. |
A single draft can combine several instructions, from different programs, into one transaction that executes all of them together.
For operations you repeat, enable **Keep draft after initiation** to reuse the draft. To inspect or reuse the instructions in other tools, select **Export as base58**. The export is the unsigned inner transaction, not the Squad proposal, so it cannot be executed on the vault's behalf elsewhere.
## How the Transaction Builder works
The Transaction Builder creates transaction drafts that you populate with one or more instructions before initiating. Each draft can contain multiple instructions targeting different programs, all executed as a single transaction.
When you create a draft, you choose how to add instructions: through an Anchor program IDL, by specifying raw Solana program accounts and data, by importing a base58- or base64-encoded transaction, or by using a predefined template. Once your instructions are assembled, simulate the transaction to verify correctness, then initiate it for Squad approval.
All custom transactions start as drafts. Save drafts for future reuse by enabling **Keep draft after initiation**. Drafts are stored in your browser, so they are not shared with other members or available on another device.
## Signers in Transaction Builder instructions
When building instructions that will execute from your Squad, the signer for your inner instructions must be the **vault PDA** (the vault address executing the transaction), not the multisig address. The Squads program signs on behalf of the vault during execution.
Setting the multisig PDA as a signer will cause simulation to pass but execution to fail or hang indefinitely. The multisig PDA is a data account owned by the Squads program and cannot sign or pay for anything.
If your instruction requires an additional signer beyond the vault (for example, a second keypair), use **ephemeral signers**. Ephemeral signers allow a derived keypair to be used for a specific transaction. To use one, mark the account as **Ephemeral** in the instruction form. Its address is computed at initiation. Alternatively, restructure your instruction so that only the vault needs to sign. You cannot have a random keypair sign a wrapped Squad transaction unless that keypair also signs during execution.
## Create a transaction draft
In the sidebar, open **Developers** and select **Tx Builder**.
Select **Create transaction**.
Choose from:
* **Custom transaction** to build from scratch (Anchor or native Solana programs)
* **Import from base58 / base64** to import an existing transaction
* **Token program**, **Stake program**, **Vote program**, or **Stake Pool program** to use a predefined template
Give your transaction draft a **Title** and, optionally, a **Description**. The description is submitted as the onchain note.
Add instructions using one of the methods below.
### Adding instructions: Anchor programs
1. Select **Add instruction** and select **Custom transaction**
2. In the **Anchor** tab, enter the **Program ID** and select **Load IDL**, or select **Import local IDL** to load the program's IDL file (JSON, up to 3 MB)
3. Select the desired instruction from the list
4. Fill in the required accounts and parameters
5. Select **Add instruction** to add the instruction
### Adding instructions: native Solana programs
1. Select **Add instruction** and select **Custom transaction**
2. Switch to the **Solana** tab (for programs written in native Rust without an Anchor IDL)
3. Enter the **Program ID**
4. Enter the account information (mark each account as **Signer**, **Writable**, or **Ephemeral** as needed) and select the data format (**Buffer** or **Raw**)
5. Select **Add instruction** to add the instruction
### Adding instructions: base58 or base64 import
1. Select **Add instruction** and select **Base58 / base64 import**
2. Paste the base58- or base64-encoded transaction and select **Decode**
3. Review the decoded instructions and any address lookup tables
4. Select the **Add instruction(s)** button, which shows the number of decoded instructions, to add them to your draft
**Imported transactions lose any pre-existing signatures.** If your original transaction was partially signed by additional keypairs, those signatures will be stripped on import. Simulation will still show success because simulation skips signature verification, but execution will fail or hang indefinitely waiting for the missing signer. For instructions requiring a second keypair signer, use ephemeral signers or restructure the instruction so that only the vault signs.
The import accepts legacy, v0, and v1 transactions in base58 or base64, so no conversion is needed. For a versioned transaction, the address lookup tables it references are fetched and added to the draft with the instructions.
### Using predefined templates
Select a template when creating your draft to get a preconfigured instruction format:
* **Token program:** Transfer tokens and close token accounts
* **Stake program:** Authorize, delegate, split, merge, deactivate, withdraw, and move stake
* **Vote program:** Change withdraw authority, withdraw stake rewards, change validator commission, and change the block revenue or inflation rewards collector
* **Stake Pool program:** Set manager, staker, fees, and funding authority of stake pools
Fill in the required fields for the selected template and select **Add instruction**.
### Simulate and initiate
1. Review your assembled instructions in the draft view
2. (Optional) Add **Address lookup tables** to reduce transaction size for complex instructions
3. Select **Simulate** to verify the transaction will execute correctly
4. Select **Initiate transaction** to submit the transaction for Squad approval. The draft's **Description** is submitted as the note
5. Once the transaction reaches the threshold and is executed, the onchain interaction completes
You can enable **Keep draft after initiation** to preserve the draft for future reuse, or select **Export as base58** to copy the transaction to your clipboard and share it externally.
## Best practices
* **Simulate before initiating.** Simulations catch incorrect accounts, missing signers, and other instruction errors before the transaction enters the approval flow.
* **Use Address Lookup Tables for complex transactions.** Transactions with many accounts can exceed Solana's size limits. Adding lookup tables compresses the transaction.
* **Save reusable drafts.** Enable **Keep draft after initiation** for transactions you expect to repeat, such as periodic validator operations.
* **Verify program addresses.** Confirm the program ID matches the official deployment before adding instructions. Interacting with the wrong program can result in lost funds.
* **Use the vault PDA as the signer**, not the multisig address, for all inner instruction accounts that require a signer.
* **Account for Squads wrapping overhead** when estimating transaction size. Keep inner transaction messages under approximately 1,000 bytes to avoid size errors.
| Issue | Solution |
| - | - |
| Simulation fails | Incorrect accounts or parameters. Review instruction data and verify all account addresses are correct |
| Transaction too large | Too many accounts or too much instruction data. See [Resolving transaction size errors](#resolving-transaction-size-errors) below |
| Transaction too large (with Fee Relayer) | Fee Relayer adds extra bytes to the transaction. Disable the Fee Relayer, fund your SquadsX pubkey with SOL, and retry |
| IDL not loading | Program doesn't publish an onchain IDL. Use **Import local IDL** to load the IDL file manually, or switch to the **Solana** tab for raw instruction input |
| Draft won't initiate | No instructions added. Add at least one instruction before initiating |
| Simulation succeeds but execution fails (hangs at confirming) | Imported transaction had extra signatures that were stripped on import. Use ephemeral signers for instructions requiring a second signer, or restructure so only the vault signs |
| Simulation succeeds but execution fails (privilege escalation error) | Wrong keypair or address used as signer in instruction accounts. Ensure the vault PDA is used as the signer in inner instructions, not the multisig PDA or a random keypair. The multisig PDA cannot sign transactions |
| Simulation succeeds but execution fails (general) | Program state changed between simulation and execution. Re-simulate with current state and initiate a new transaction |
| "BPFLoaderUpgradeable not supported by inner instructions" | While Solana supports CPI calls to BPFLoaderUpgradeable for many operations (including `Upgrade` and `ExtendProgram`), the Transaction Builder may not handle all of them. Try using the Squads CLI or SDK to craft the transaction programmatically, or contact support |
### Resolving transaction size errors
Legacy and v0 Solana transactions are limited to 1,232 bytes. Squads wraps your inner instructions into a multisig transaction, adding approximately 150 to 200 bytes of overhead. This means your inner transaction message should stay under approximately 1,000 bytes. A transaction that works from a regular wallet may exceed the limit when executed through Squads.
Wallets that support the larger Solana v1 transaction format, such as Solflare or Jupiter, can propose and execute transactions of up to 4,096 bytes. Hardware wallets do not support it. If the TX Builder reports that the transaction is too large for your wallet's transaction format, propose it with a wallet that supports v1, or reduce its size.
To resolve size errors:
* **Use Address Lookup Tables** to reference accounts by a 1-byte index instead of a full 32-byte public key, saving 31 bytes per account. Signers and program IDs must still appear inline.
* **Split instructions across multiple transactions.** Import your base58-encoded transaction, keep only the first group of instructions (such as token account creation), execute it, then re-import and repeat with the next group.
* **Reduce the number of accounts** in a single instruction where possible.
* **Disable the Fee Relayer** if enabled, as it adds extra bytes. Fund your SquadsX pubkey with SOL to pay fees instead.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.