---
name: swig-smart-wallet
description: >
  Create and manage Solana smart wallets using the Swig TypeScript SDK.
  This skill enables AI agents to generate Swig wallets, manage authorities
  (add/remove/update with granular permissions), execute transactions through
  the wallet, and handle gas sponsorship via the Swig Paymaster API, a custom
  gas server, or self-funded SOL. Works with both @swig-wallet/classic
  (web3.js 1.x) and @swig-wallet/kit (@solana/kit 2.x).
---

# Swig Smart Wallet Skill

You are an AI agent that can create and manage Solana smart wallets using the Swig protocol. Swig wallets are on-chain programmable wallets with granular authority and permission management. You write TypeScript scripts that use the Swig SDK to perform wallet operations.

## Prerequisites

Before doing anything, you MUST gather the following from the user:

### 1. Solana RPC Endpoint

Ask the user: "What Solana RPC endpoint should I use for transactions?"

Acceptable answers:

- A specific URL (e.g. `https://api.mainnet-beta.solana.com`, `https://api.devnet.solana.com`, or a custom RPC like Helius, Triton, etc.)
- "devnet" — use `https://api.devnet.solana.com`
- "mainnet" — use `https://api.mainnet-beta.solana.com`
- "localnet" or "localhost" — use `http://localhost:8899`

If the user does not know, suggest they use devnet for testing: `https://api.devnet.solana.com`

Store the RPC URL in an environment variable `SOLANA_RPC_URL` or in a `.env` file.

### 2. Gas / Fee Sponsorship

Ask the user: "How would you like transaction fees to be handled?"

Present these three options:

**Option A — Swig Paymaster (recommended for production)**
The Swig Paymaster API covers transaction fees. Ask the user to provide:

- Their **API Key** from `dashboard.onswig.com`
- Their **Paymaster Public Key** from `dashboard.onswig.com`
- The **network** they want to use: `mainnet` or `devnet`

Store these as environment variables:

```
SWIG_PAYMASTER_API_KEY=<their-api-key>
SWIG_PAYMASTER_PUBKEY=<their-paymaster-pubkey>
SWIG_PAYMASTER_NETWORK=devnet
```

**Option B — Custom Gas Sponsorship Server**
The user runs their own server that signs/sponsors transactions. Ask for:

- The **API URL** of their gas sponsorship server

Store as:

```
GAS_SPONSOR_URL=<their-server-url>
```

**Option C — Self-funded (agent pays its own fees)**
The agent generates its own Solana keypair and pays fees from its own balance. The user must send a small amount of SOL (0.01-0.1 SOL) to the agent's address.

When using this option:

1. Generate a new Ed25519 keypair for the agent
2. Save the keypair securely to a file (e.g. `agent-keypair.json`)
3. Display the public key to the user
4. Ask: "Please send a small amount of SOL (at least 0.01 SOL) to `<agent-public-key>` and let me know when done."
5. Verify the balance before proceeding

## SDK Choice

The Swig SDK comes in two flavors. Choose based on the project:

| Package                | Solana SDK             | When to Use                                                         |
| ---------------------- | ---------------------- | ------------------------------------------------------------------- |
| `@swig-wallet/classic` | `@solana/web3.js` v1.x | Existing projects using web3.js v1, broader ecosystem compatibility |
| `@swig-wallet/kit`     | `@solana/kit` v2.x     | New projects, modern Solana development                             |

If the user has no preference, default to `@swig-wallet/classic` for broader compatibility.

## Installation

```bash
# For classic (web3.js 1.x)
npm install @swig-wallet/classic @solana/web3.js

# For kit (@solana/kit 2.x)
npm install @swig-wallet/kit @solana/kit

# For paymaster support (add one based on SDK choice)
npm install @swig-wallet/paymaster-classic
# or
npm install @swig-wallet/paymaster-kit
```

## Core Operations

### 1. Create a Swig Wallet

A Swig wallet is created on-chain with:

- A random 32-byte **ID** (used to derive the PDA address)
- A **root authority** (the initial owner, typically an Ed25519 public key)
- **Root actions/permissions** (typically `Actions.set().all().get()` for full control)

#### Classic Example

```typescript
import {
  Connection,
  Keypair,
  Transaction,
  sendAndConfirmTransaction,
} from '@solana/web3.js';
import {
  Actions,
  createEd25519AuthorityInfo,
  fetchSwig,
  findSwigPda,
  getCreateSwigInstruction,
  getSwigWalletAddress,
} from '@swig-wallet/classic';

const connection = new Connection(process.env.SOLANA_RPC_URL!, 'confirmed');
const payer = Keypair.fromSecretKey(/* loaded from file or env */);

// 1. Generate random 32-byte Swig ID
const id = new Uint8Array(32);
crypto.getRandomValues(id);

// 2. Derive the Swig account PDA
const swigAccountAddress = findSwigPda(id);

// 3. Create root authority info from the payer's pubkey
const rootAuthorityInfo = createEd25519AuthorityInfo(payer.publicKey);

// 4. Set root permissions (full control)
const rootActions = Actions.set().all().get();

// 5. Build the create instruction
const createSwigIx = await getCreateSwigInstruction({
  payer: payer.publicKey,
  id,
  actions: rootActions,
  authorityInfo: rootAuthorityInfo,
});

// 6. Send transaction
const tx = new Transaction().add(createSwigIx);
const signature = await sendAndConfirmTransaction(connection, tx, [payer]);

// 7. Fetch and verify
const swig = await fetchSwig(connection, swigAccountAddress);
const walletAddress = await getSwigWalletAddress(swig);

console.log('Swig account:', swigAccountAddress.toBase58());
console.log('Swig wallet address:', walletAddress.toBase58());
```

#### Kit Example

```typescript
import {
  createSolanaRpc,
  createSolanaRpcSubscriptions,
  generateKeyPairSigner,
  sendAndConfirmTransactionFactory,
  signTransaction,
  pipe,
  createTransactionMessage,
  setTransactionMessageFeePayer,
  setTransactionMessageLifetimeUsingBlockhash,
  appendTransactionMessageInstructions,
  compileTransaction,
  getSignatureFromTransaction,
} from '@solana/kit';
import {
  Actions,
  createEd25519AuthorityInfo,
  fetchSwig,
  findSwigPda,
  getCreateSwigInstruction,
  getSwigWalletAddress,
} from '@swig-wallet/kit';

const rpc = createSolanaRpc(process.env.SOLANA_RPC_URL!);
const rpcSubscriptions = createSolanaRpcSubscriptions(
  process.env.SOLANA_RPC_URL!.replace('https', 'wss'),
);
const payer = await generateKeyPairSigner();

const id = new Uint8Array(32);
crypto.getRandomValues(id);
const swigAccountAddress = await findSwigPda(id);

const rootAuthorityInfo = createEd25519AuthorityInfo(payer.address);
const rootActions = Actions.set().all().get();

const createSwigIx = await getCreateSwigInstruction({
  payer: payer.address,
  id,
  actions: rootActions,
  authorityInfo: rootAuthorityInfo,
});

const { value: blockhash } = await rpc.getLatestBlockhash().send();
const txMessage = pipe(
  createTransactionMessage({ version: 0 }),
  (m) => setTransactionMessageFeePayer(payer.address, m),
  (m) => setTransactionMessageLifetimeUsingBlockhash(blockhash, m),
  (m) => appendTransactionMessageInstructions([createSwigIx], m),
);
const compiledTx = compileTransaction(txMessage);
const signedTx = await signTransaction([payer.keyPair], compiledTx);

await sendAndConfirmTransactionFactory({ rpc, rpcSubscriptions })(signedTx, {
  commitment: 'confirmed',
});

const swig = await fetchSwig(rpc, swigAccountAddress);
const walletAddress = await getSwigWalletAddress(swig);
```

### 2. Add an Authority

Authorities are additional keys that can interact with the Swig wallet, each with specific permissions.

```typescript
import {
  fetchSwig,
  getAddAuthorityInstructions,
  createEd25519AuthorityInfo,
  Actions,
} from '@swig-wallet/classic';

const swig = await fetchSwig(connection, swigAccountAddress);
const rootRole = swig.findRolesByEd25519SignerPk(rootKeypair.publicKey)[0];

// Create a new authority with specific permissions
const newAuthorityInfo = createEd25519AuthorityInfo(newKeypair.publicKey);

// Example permissions: 0.5 SOL spend limit
const actions = Actions.set()
  .solLimit({ amount: 500_000_000n }) // 0.5 SOL in lamports
  .get();

const ixs = await getAddAuthorityInstructions(
  swig,
  rootRole.id,
  newAuthorityInfo,
  actions,
);

const tx = new Transaction().add(...ixs);
await sendAndConfirmTransaction(connection, tx, [rootKeypair]);
```

### 3. Remove an Authority

```typescript
import {
  getRemoveAuthorityInstructions,
  fetchSwig,
} from '@swig-wallet/classic';

const swig = await fetchSwig(connection, swigAccountAddress);
const rootRole = swig.findRolesByEd25519SignerPk(rootKeypair.publicKey)[0];

// Find the role ID of the authority to remove
const roleToRemove = swig.findRolesByEd25519SignerPk(targetPubkey)[0];

const ixs = await getRemoveAuthorityInstructions(
  swig,
  rootRole.id,
  roleToRemove.id,
);

const tx = new Transaction().add(...ixs);
await sendAndConfirmTransaction(connection, tx, [rootKeypair]);
```

### 4. Update Authority Permissions

```typescript
import {
  getUpdateAuthorityInstructions,
  updateAuthorityReplaceAllActions,
  updateAuthorityAddActions,
  updateAuthorityRemoveByType,
  Actions,
  Permission,
  fetchSwig,
} from '@swig-wallet/classic';

const swig = await fetchSwig(connection, swigAccountAddress);
const rootRole = swig.findRolesByEd25519SignerPk(rootKeypair.publicKey)[0];
const roleToUpdate = swig.findRolesByEd25519SignerPk(targetPubkey)[0];

// Option 1: Replace all actions
const updateInfo = updateAuthorityReplaceAllActions(
  Actions.set().solLimit({ amount: 1_000_000_000n }).programAll().get(),
);

// Option 2: Add new actions
// const updateInfo = updateAuthorityAddActions(
//   Actions.set().tokenLimit({ mint: tokenMintPubkey, amount: 1_000_000n }).get()
// );

// Option 3: Remove actions by type
// const updateInfo = updateAuthorityRemoveByType([Permission.SolLimit]);

const ixs = await getUpdateAuthorityInstructions(
  swig,
  rootRole.id,
  roleToUpdate.id,
  updateInfo,
);

const tx = new Transaction().add(...ixs);
await sendAndConfirmTransaction(connection, tx, [rootKeypair]);
```

### 5. Execute Transactions Through the Swig Wallet

The Swig wallet acts as the signer for inner instructions. Use `getSignInstructions` to wrap any instruction so it executes from the Swig wallet.

```typescript
import { SystemProgram } from '@solana/web3.js';
import {
  getSignInstructions,
  getSwigWalletAddress,
  fetchSwig,
} from '@swig-wallet/classic';

const swig = await fetchSwig(connection, swigAccountAddress);
const walletAddress = await getSwigWalletAddress(swig);
const role = swig.findRolesByEd25519SignerPk(signerKeypair.publicKey)[0];

// Build the inner instruction (SOL transfer from the Swig wallet)
const transferIx = SystemProgram.transfer({
  fromPubkey: walletAddress,
  toPubkey: recipientPubkey,
  lamports: 100_000_000, // 0.1 SOL
});

// Wrap it with Swig signing
const signedIxs = await getSignInstructions(swig, role.id, [transferIx]);

const tx = new Transaction().add(...signedIxs);
await sendAndConfirmTransaction(connection, tx, [signerKeypair]);
```

### 6. Using the Paymaster (Gasless Transactions)

#### Classic Paymaster

```typescript
import { Keypair } from '@solana/web3.js';
import { createPaymasterClient } from '@swig-wallet/paymaster-classic';

const paymaster = createPaymasterClient({
  apiKey: process.env.SWIG_PAYMASTER_API_KEY!,
  paymasterPubkey: process.env.SWIG_PAYMASTER_PUBKEY!,
  baseUrl: 'https://api.onswig.com',
  network: process.env.SWIG_PAYMASTER_NETWORK as 'mainnet' | 'devnet',
});

// Build your instructions normally, then:
const tx = await paymaster.createLegacyTransaction(
  [instruction1, instruction2],
  [userKeypair], // user signs
);

// Paymaster signs and sends
const signature = await paymaster.signAndSend(tx);
```

#### Kit Paymaster

```typescript
import { partiallySignTransaction } from '@solana/kit';
import { createPaymasterClient } from '@swig-wallet/paymaster-kit';

const paymaster = createPaymasterClient({
  apiKey: process.env.SWIG_PAYMASTER_API_KEY!,
  paymasterPubkey: process.env.SWIG_PAYMASTER_PUBKEY!,
  baseUrl: 'https://api.onswig.com',
  network: process.env.SWIG_PAYMASTER_NETWORK as 'mainnet' | 'devnet',
});

const unsignedTx = await paymaster.createTransaction([instruction]);
const partiallySignedTx = await partiallySignTransaction(
  [userKeypair.keyPair],
  unsignedTx,
);
const fullySignedTx = await paymaster.fullySign(partiallySignedTx);

await sendAndConfirmTransactionFactory({ rpc, rpcSubscriptions })(
  fullySignedTx,
  { commitment: 'confirmed' },
);
```

### 7. Custom Gas Sponsorship Server

If the user has their own gas server, send the serialized transaction to it for signing:

```typescript
async function sponsorTransaction(
  serializedTx: Uint8Array,
  sponsorUrl: string,
): Promise<Uint8Array> {
  const response = await fetch(`${sponsorUrl}/sponsor`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      transaction: Buffer.from(serializedTx).toString('base64'),
    }),
  });
  const { signedTransaction } = await response.json();
  return Buffer.from(signedTransaction, 'base64');
}
```

## Available Permission Types

Use the `Actions` builder to set permissions for authorities:

| Method                                                                            | Description                                      |
| --------------------------------------------------------------------------------- | ------------------------------------------------ |
| `.all()`                                                                          | Full root permissions (everything)               |
| `.manageAuthority()`                                                              | Can add/remove/update other authorities          |
| `.allButManageAuthority()`                                                        | Everything except managing authorities           |
| `.closeSwigAuthority()`                                                           | Can close the Swig account                       |
| `.solLimit({ amount })`                                                           | One-time SOL spend limit (in lamports as bigint) |
| `.solRecurringLimit({ recurringAmount, window })`                                 | Recurring SOL limit (window in slots)            |
| `.solDestinationLimit({ amount, destination })`                                   | SOL limit to specific recipient                  |
| `.solRecurringDestinationLimit({ recurringAmount, window, destination })`         | Recurring SOL to specific recipient              |
| `.tokenLimit({ mint, amount })`                                                   | One-time token spend limit                       |
| `.tokenRecurringLimit({ mint, recurringAmount, window })`                         | Recurring token limit                            |
| `.tokenDestinationLimit({ mint, amount, destination })`                           | Token limit to specific recipient                |
| `.tokenRecurringDestinationLimit({ mint, recurringAmount, window, destination })` | Recurring token to specific recipient            |
| `.programLimit({ programId })`                                                    | Can interact with a specific program             |
| `.programAll()`                                                                   | Can interact with any program                    |
| `.programCurated()`                                                               | Can interact with curated programs               |
| `.subAccount()`                                                                   | Can create/manage sub-accounts                   |
| `.stakeAll()`                                                                     | Full staking permissions                         |
| `.stakeLimit({ amount })`                                                         | Staking with amount limit                        |

Combine permissions by chaining:

```typescript
const actions = Actions.set()
  .solLimit({ amount: 1_000_000_000n }) // 1 SOL limit
  .tokenLimit({ mint: usdcMint, amount: 100_000_000n }) // 100 USDC
  .programLimit({ programId: jupiterProgramId }) // Jupiter access
  .get();
```

## Authority Types

| Type            | Function                                                    | Use Case                |
| --------------- | ----------------------------------------------------------- | ----------------------- |
| Ed25519         | `createEd25519AuthorityInfo(publicKey)`                     | Standard Solana keypair |
| Ed25519 Session | `createEd25519SessionAuthorityInfo(publicKey, maxDuration)` | Time-limited Ed25519    |
| Secp256k1       | `createSecp256k1AuthorityInfo(publicKey)`                   | Ethereum-style keys     |
| Secp256r1       | `createSecp256r1AuthorityInfo(publicKey)`                   | Passkeys / WebAuthn     |

## Agent Identity Key Setup (Self-Funded)

When the agent needs its own keypair:

```typescript
import { Keypair } from '@solana/web3.js';
import fs from 'fs';

// Generate and save
const agentKeypair = Keypair.generate();
fs.writeFileSync(
  'agent-keypair.json',
  JSON.stringify(Array.from(agentKeypair.secretKey)),
);
console.log('Agent public key:', agentKeypair.publicKey.toBase58());

// Load later
const loaded = Keypair.fromSecretKey(
  new Uint8Array(JSON.parse(fs.readFileSync('agent-keypair.json', 'utf-8'))),
);
```

## Important Constants

- **Swig Program ID**: `swigypWHEksbC64pWKwah1WTeh9JXwx8H1rJHLdbQMB`
- **1 SOL** = `1_000_000_000` lamports (use `BigInt` or `n` suffix)
- **Swig Paymaster Dashboard**: `dashboard.onswig.com`

## Workflow Summary

1. **Gather config**: RPC URL, gas strategy, SDK choice
2. **Install packages**: `@swig-wallet/classic` or `@swig-wallet/kit` (+ paymaster if needed)
3. **Set up identity**: Load or generate a keypair
4. **Create Swig wallet**: Generate ID, derive PDA, send create instruction
5. **Fund the wallet**: Transfer SOL to the Swig wallet address
6. **Add authorities**: Grant granular permissions to other keys
7. **Transact**: Wrap inner instructions with `getSignInstructions` to execute from the wallet
8. **Manage**: Update or remove authorities as needed

## Error Handling

Always wrap transactions in try/catch and handle common errors:

- Insufficient balance (need SOL for rent + fees)
- Authority not found (refetch swig before operations)
- Permission denied (authority lacks required actions)
- Spend limit exceeded (authority has already used its allowance)

Always call `swig.refetch()` before building new instructions to ensure you have the latest on-chain state.