# Deep Dive
Source: https://build.onswig.com/deepdive

"I swig therefor I am" - Rene Descartes using Swig

# Deep Dive

Let's dive into how Swig works under the hood! I'm excited to share some of the cool technical innovations we've built to make Swig blazing fast while maintaining rock-solid security.

## The Need for Speed 🏃‍♂️

When we started building Swig, we knew that smart wallets needed to be FAST. Like, really fast. Nobody wants to wait around for their transactions, especially in DeFi where every millisecond counts. This led us down a fascinating path of optimization at every level of the stack.

## Zero-Copy Architecture

One of our proudest achievements is Swig's zero-copy architecture. Instead of constantly allocating and copying data around (which is slow and expensive), we've built Swig to work directly with data in place whenever possible. We use Rust's powerful zero-copy parsing capabilities through libraries like Pinnochio to handle instruction data and account parsing with minimal overhead.

This means when you send a transaction through Swig, we're not wasting time shuffling data around - we're getting straight to the important stuff like signature verification and permission checks.

## Smart Account Classification

A key innovation in Swig is our account classification system. When a transaction comes in, we need to know exactly what we're dealing with - is this a Swig account? A token account? Something else entirely?

We've built a lightning-fast classification engine that can identify account types and validate their structure in a single pass. This isn't just about speed - it's also a critical security feature that ensures we're always working with exactly the account types we expect.

The classification system uses a combination of:

* Account ownership checks
* Data structure validation
* PDA derivation verification

All of this happens automatically at the program entry point, so by the time we get to instruction processing, we know exactly what we're working with.

## Extensible Authority System

While speed is crucial, flexibility is just as important. That's why we built Swig with an extensible authority system that can grow with the ecosystem. Right now, we support Ed25519 and Secp256k1 signatures, but that's just the beginning.

We've designed the system so we can continuously add new authority types without breaking existing functionality. Some exciting things we're working on include:

* Program-based authorities (letting other Solana programs act as authorities)
* Groth16 zero-knowledge proof authorities (for privacy-preserving operations)
* Simplified EVM-compatible authority systems (making it easier to bridge from Ethereum)

## Permission System That Makes Sense

Security doesn't have to be complicated. We've built a permission system that's both powerful and intuitive. Whether you need to:

* Manage specific tokens
* Set spending limits
* Control program access
* Set time-based restrictions

It all just works, and more importantly, it's easy to understand and audit.

## Looking Forward 🔭

We're not stopping here! Some exciting things in the pipeline:

### Paymaster Network

We're working on a decentralized paymaster network that will make gas-less transactions accessible to everyone. This is a game-changer for user experience, especially for newcomers to Solana.

### More Authority Types

The crypto ecosystem is constantly evolving, and so is Swig. We're actively working on supporting more signature schemes and authority types to make Swig the most versatile smart wallet platform out there.

### Enhanced Performance

While we're already blazing fast, we're constantly finding new ways to optimize. Our team is obsessed with performance, and we're always looking for ways to squeeze out every last bit of efficiency.

## Wrapping Up

Swig is more than just a smart wallet - it's a platform built for the future of decentralized finance. By combining cutting-edge performance optimizations with a flexible, extensible architecture, we're creating something that can grow and evolve with the ecosystem.

Stay tuned for more updates, and feel free to dive into our docs to learn more about specific features and implementations. We're just getting started! 🚀


# Credit Card Processing with SWIG
Source: https://build.onswig.com/examples/credit_card

"Give a man a credit card, and he'll buy coffee for a day. Teach him to Swig, and he'll sign for it himself."— DeFi Proverb

SWIG provides robust support for both credit and debit card payment flows through its authority system and authorization locks feature. Watch our quick demo to see it in action:

<iframe />

## How It Works

SWIG can handle both debit and credit card flows in a way that's both elegant and compliant. Our authority system forms the foundation, giving you complete control over who can spend what and when, while our authorization locks enable sophisticated payment flows that traditional finance demands.

### Debit Card Processing

When it comes to debit cards, things are pretty straightforward. Using our standard spending limits, you can pull funds directly into your treasury account. Think of it as an instant transfer – the money moves right away, and you can start using it immediately. Our authority system ensures that only authorized parties can initiate these transfers, and you can set custom limits that make sense for your business.

### Credit Card Magic

Credit cards are where things get interesting. Instead of immediately pulling funds, our authorization locks system lets you place a hold on the funds first. This is perfect for situations where you need to verify a card's validity and ensure funds are available, but aren't ready to complete the transaction yet. The authorization lock is incredibly fast and cost-effective, and it keeps the funds reserved until the credit card provider is ready to process the payment according to their jurisdiction's rules and requirements.

This approach is particularly valuable in industries with complex payment flows. For example, if you're running a car rental service, you can authorize a security deposit without actually charging it, then only capture the final amount once the rental period is complete. Hotels, travel companies, and any business dealing with delayed or variable charges will find this especially useful.

## Why Choose SWIG

Our payment infrastructure isn't just about moving money – it's about giving you the tools to build sophisticated financial products. With our authority system handling permissions and our authorization locks managing holds, you can focus on building your product while we handle the complex payment orchestration behind the scenes.

Ready to revolutionize your payment flows? Get in touch with our team, and we'll help you get started with SWIG's credit card processing capabilities.

contact: [info@onswig.com](mailto:info@onswig.com)


# REST API Reference
Source: https://build.onswig.com/examples/dev-portal/api-reference

"The API is the contract between your code and our service" - Swig Engineering

This reference documents the Swig Developer Portal REST API endpoints.

## Base URLs

| Environment   | URL                            |
| ------------- | ------------------------------ |
| Portal API    | `https://dashboard.onswig.com` |
| Paymaster API | `https://api.onswig.com`       |

## Authentication

All API requests require authentication via API key:

```
Authorization: Bearer sk_your_api_key
```

API keys are created in the [Developer Portal](https://dashboard.onswig.com) and have the format `sk_<64-hex-characters>`.

## Endpoints

### Policies

#### Get Policy

Retrieve a policy by ID.

**Request:**

```
GET /api/v1/policies/{policyId}
```

**Headers:**

```
Authorization: Bearer sk_your_api_key
```

**Path Parameters:**

| Parameter  | Type   | Description                 |
| ---------- | ------ | --------------------------- |
| `policyId` | string | The policy ID (CUID format) |

**Response:**

```json theme={null}
{
  "id": "clx1234567890abcdef",
  "name": "user-wallet-policy",
  "description": "Standard user wallet with transfer limits",
  "authority": {
    "type": "Ed25519",
    "publicKey": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU"
  },
  "actions": [
    { "type": "SolLimit", "amount": "1000000000" },
    { "type": "TokenLimit", "mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", "amount": "1000000" }
  ]
}
```

**cURL Example:**

```bash theme={null}
curl -X GET "https://dashboard.onswig.com/api/v1/policies/clx1234567890abcdef" \
  -H "Authorization: Bearer sk_your_api_key"
```

***

### Wallets

#### Create Wallet

Create a new Swig wallet using a policy.

**Request:**

```
POST /api/v1/wallet/create
```

**Headers:**

```
Authorization: Bearer sk_your_api_key
Content-Type: application/json
```

**Request Body:**

| Field             | Type   | Required | Description                                |
| ----------------- | ------ | -------- | ------------------------------------------ |
| `policyId`        | string | Yes      | Policy ID to use                           |
| `network`         | string | Yes      | `"mainnet"` or `"devnet"`                  |
| `paymasterPubkey` | string | Yes      | Paymaster public key                       |
| `swigId`          | string | No       | Custom Swig ID (auto-generated if omitted) |
| `signerId`        | string | No       | Signer ID override                         |

**Request Example:**

```json theme={null}
{
  "policyId": "clx1234567890abcdef",
  "network": "devnet",
  "paymasterPubkey": "A1dBRAaYUHyUzyQLGYzHrQzpYy9xTVXCaMnHx4RuEGY5"
}
```

**Response:**

```json theme={null}
{
  "swigId": "a1b2c3d4e5f67890",
  "swigAddress": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
  "signature": "5wHu1qwD7g4p3zWxF..."
}
```

**cURL Example:**

```bash theme={null}
curl -X POST "https://dashboard.onswig.com/api/v1/wallet/create" \
  -H "Authorization: Bearer sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "policyId": "clx1234567890abcdef",
    "network": "devnet",
    "paymasterPubkey": "A1dBRAaYUHyUzyQLGYzHrQzpYy9xTVXCaMnHx4RuEGY5"
  }'
```

***

### Paymaster

#### Sponsor Transaction

Submit a transaction for sponsorship.

**Request:**

```
POST /sponsor
```

**Base URL:** `https://api.onswig.com`

**Headers:**

```
Authorization: Bearer sk_your_api_key
Content-Type: application/json
```

**Request Body:**

| Field                        | Type   | Required | Description                |
| ---------------------------- | ------ | -------- | -------------------------- |
| `base58_encoded_transaction` | string | Yes      | Base58-encoded transaction |
| `network`                    | string | No       | `"mainnet"` or `"devnet"`  |

**Request Example:**

```json theme={null}
{
  "base58_encoded_transaction": "BASE58_ENCODED_TX_HERE",
  "network": "devnet"
}
```

**Response:**

```json theme={null}
{
  "request_id": "req_abc123",
  "signature": "5wHu1qwD7g4p3zWxF...",
  "spent_by_paymaster": 5000
}
```

**Response Fields:**

| Field                | Type   | Description                 |
| -------------------- | ------ | --------------------------- |
| `request_id`         | string | Unique request identifier   |
| `signature`          | string | Transaction signature       |
| `spent_by_paymaster` | number | Lamports spent by paymaster |

***

#### Sign Transaction

Sign a transaction without sending.

**Request:**

```
POST /sign
```

**Base URL:** `https://api.onswig.com`

**Headers:**

```
Authorization: Bearer sk_your_api_key
Content-Type: application/json
```

**Request Body:**

| Field                        | Type   | Required | Description                |
| ---------------------------- | ------ | -------- | -------------------------- |
| `base58_encoded_transaction` | string | Yes      | Base58-encoded transaction |
| `network`                    | string | No       | `"mainnet"` or `"devnet"`  |

**Response:**

```json theme={null}
{
  "request_id": "req_abc123",
  "signed_transaction": "BASE58_ENCODED_SIGNED_TX"
}
```

***

#### Health Check

Check paymaster service health.

**Request:**

```
GET /health
```

**Base URL:** `https://api.onswig.com`

**Response:**

```json theme={null}
{
  "status": "healthy",
  "timestamp": "2024-01-15T12:00:00Z"
}
```

***

## Data Types

### Policy

```typescript theme={null}
interface Policy {
  id: string;
  name: string;
  description: string | null;
  authority: AuthorityConfig | null;
  actions: ActionConfig[];
}
```

### AuthorityConfig

```typescript theme={null}
type AuthorityConfig =
  | { type: 'Ed25519'; publicKey: string }
  | { type: 'Ed25519Session'; publicKey: string; maxDurationSlots: string }
  | { type: 'Secp256k1'; publicKey: string }
  | { type: 'Secp256k1Session'; publicKey: string; maxDurationSlots: string }
  | { type: 'Secp256r1'; publicKey: string }
  | { type: 'Secp256r1Session'; publicKey: string; maxDurationSlots: string };
```

### ActionConfig

```typescript theme={null}
type ActionConfig =
  // General
  | { type: 'All' }
  | { type: 'AllButManageAuthority' }
  | { type: 'ManageAuthority' }

  // SOL
  | { type: 'SolLimit'; amount: string }
  | { type: 'SolRecurringLimit'; recurringAmount: string; window: string }
  | { type: 'SolDestinationLimit'; amount: string; destination: string }
  | { type: 'SolRecurringDestinationLimit'; recurringAmount: string; window: string; destination: string }

  // Token
  | { type: 'TokenLimit'; mint: string; amount: string }
  | { type: 'TokenRecurringLimit'; mint: string; recurringAmount: string; window: string }
  | { type: 'TokenDestinationLimit'; mint: string; amount: string; destination: string }
  | { type: 'TokenRecurringDestinationLimit'; mint: string; recurringAmount: string; window: string; destination: string }

  // Program
  | { type: 'Program'; programId: string }
  | { type: 'ProgramAll' }
  | { type: 'ProgramCurated' }

  // Staking
  | { type: 'StakeLimit'; amount: string }
  | { type: 'StakeRecurringLimit'; recurringAmount: string; window: string }
  | { type: 'StakeAll' }

  // Sub-accounts
  | { type: 'SubAccount' };
```

### CreateWalletRequest

```typescript theme={null}
interface CreateWalletRequest {
  policyId: string;
  network: 'mainnet' | 'devnet';
  paymasterPubkey: string;
  swigId?: string;
  signerId?: string;
}
```

### CreateWalletResponse

```typescript theme={null}
interface CreateWalletResponse {
  swigId: string;
  swigAddress: string;
  signature: string;
}
```

## Error Responses

All errors follow this format:

```json theme={null}
{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": {}
  }
}
```

See [Error Codes](./error-codes) for a complete list.

## Rate Limits

API requests are rate-limited based on your subscription tier:

| Tier       | Requests/Minute |
| ---------- | --------------- |
| FREE       | 60              |
| PRO        | 300             |
| ULTRA      | 600             |
| ENTERPRISE | Custom          |

Rate limit headers are included in responses:

```
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1642520400
```

## SDKs

Use our SDKs for easier integration:

<Tabs>
  <Tab title="API SDK">
    ```bash theme={null}
    npm install @swig-wallet/api
    ```

    ```typescript theme={null}
    import { SwigApiClient } from '@swig-wallet/api';

    const client = new SwigApiClient({
      apiKey: 'sk_your_api_key',
      portalUrl: 'https://dashboard.onswig.com',
    });
    ```
  </Tab>

  <Tab title="Developer SDK">
    ```bash theme={null}
    npm install @swig-wallet/developer
    ```

    ```typescript theme={null}
    import { SwigClient } from '@swig-wallet/developer';

    const client = new SwigClient({
      apiKey: 'sk_your_api_key',
      baseUrl: 'https://dashboard.onswig.com',
    });
    ```
  </Tab>
</Tabs>

## Next Steps

* [Error Codes](./error-codes) - Understand API errors
* [SDK Examples](./fetch-policy) - See the SDKs in action
* [Create Wallets](./create-swig) - Full wallet creation guide


# Creating an API Key
Source: https://build.onswig.com/examples/dev-portal/create-api-key

"With great API keys comes great responsibility" - Swig Security Team

API keys authenticate your applications when making requests to Swig services. This guide walks you through creating an API key in the Developer Portal.

## What API Keys Are Used For

API keys are required for:

* Fetching policy details via the REST API
* Creating Swig wallets programmatically
* Accessing paymaster services for transaction sponsorship

## Prerequisites

Before creating an API key, ensure you have:

* A Swig account at [dashboard.onswig.com](https://dashboard.onswig.com)
* Access to an organization

## Creating an API Key

### Step 1: Navigate to API Keys

1. Log in to the [Developer Portal](https://dashboard.onswig.com)
2. Select your project from the sidebar
3. Click **API Keys** in the navigation menu

### Step 2: Create New Key

1. Click the **Create API Key** button
2. Enter a **name** for your key (required, 1-100 characters)
   * Use descriptive names like `production-backend` or `dev-testing`
3. Optionally set an **expiration date**
   * Leave empty for keys that never expire
4. Click **Create**

### Step 3: Copy Your Key

<Warning>
  **Important:** Your API key is only shown once. Copy it immediately and store it securely.
  You will not be able to view the full key again.
</Warning>

After creation, the portal displays your full API key. Copy it and store it in a secure location such as:

* Environment variables
* A secrets manager (AWS Secrets Manager, HashiCorp Vault, etc.)
* Your CI/CD platform's secret storage

## API Key Format

Swig API keys follow this format:

```
sk_<64-hexadecimal-characters>
```

Example:

```
sk_a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef12345678
```

The `sk_` prefix identifies it as a Swig API key.

## Subscription Limits

API key limits depend on your subscription tier:

| Tier | API Keys Allowed |
| ---- | ---------------- |
| Free | 1                |
| Paid | Unlimited        |

<Tip>
  Need more API keys? Upgrade your subscription in the portal's billing section.
</Tip>

## Using Your API Key

### In HTTP Requests

Include your API key in the `Authorization` header:

```bash theme={null}
curl -X GET "https://dashboard.onswig.com/api/v1/policies/{policyId}" \
  -H "Authorization: Bearer sk_your_api_key"
```

### With the SDK

Pass your API key when initializing the client:

```typescript theme={null}
import { SwigApiClient } from '@swig-wallet/api';

const client = new SwigApiClient({
  apiKey: process.env.SWIG_API_KEY,
  portalUrl: 'https://dashboard.onswig.com',
});
```

## Best Practices

### Security

* **Never commit API keys** to version control
* **Use environment variables** to store keys in your application
* **Rotate keys periodically**, especially if you suspect compromise
* **Use separate keys** for development and production environments

### Naming Conventions

Use descriptive names that indicate:

* The environment (`dev-`, `staging-`, `prod-`)
* The service or application using the key
* The purpose (`backend-api`, `mobile-app`, `testing`)

Examples:

* `prod-backend-service`
* `dev-local-testing`
* `staging-mobile-app`

### Expiration

Consider setting expiration dates for:

* Temporary access (contractors, testing)
* Compliance requirements
* Regular rotation schedules

## Managing API Keys

### Viewing Keys

The API Keys page shows all your keys with:

* Name
* Creation date
* Expiration date (if set)
* Usage count
* Last used timestamp

### Deleting Keys

To revoke an API key:

1. Find the key in the API Keys table
2. Click the **Delete** action
3. Confirm deletion

<Warning>
  Deleting an API key immediately invalidates it. Any applications using that key will lose access.
</Warning>

## Next Steps

Now that you have an API key, you can:

* [Create a policy](./create-policy) to define wallet permissions
* [Fetch policies](./fetch-policy) programmatically
* [Create Swig wallets](./create-swig) via the API


# Creating an Organization
Source: https://build.onswig.com/examples/dev-portal/create-organization

"Every journey begins with a single organization" - Swig Philosophy

This guide walks you through creating a new organization in the Swig Developer Portal.

## Prerequisites

Before creating an organization, ensure you have:

* A Swig account at [dashboard.onswig.com](https://dashboard.onswig.com)
* A **verified email address** (required for organization creation)

<Warning>
  You must verify your email before creating organizations. Check your inbox for the verification link.
</Warning>

## Automatic Organization

When you first sign up for Swig, an organization is automatically created for you with:

* **You as the Owner** - Full control over the organization
* **FREE subscription** - Access to basic features
* **1 API key slot** - For programmatic access
* **1 team seat** - Just you to start

You can start using this organization immediately or create additional organizations for different projects.

## Creating a New Organization

### Step 1: Access Organization Settings

1. Log in to the [Developer Portal](https://dashboard.onswig.com)
2. Click on your organization name in the sidebar
3. Click **Create New Organization** or access via the organization dropdown

### Step 2: Enter Organization Details

1. **Organization Name** (required)
   * 1-100 characters
   * Use a descriptive name (e.g., "Acme Corp", "My DeFi Project")
   * Can be changed later

2. Click **Create Organization**

### Step 3: What Gets Created

When you create an organization, the system automatically:

1. **Creates the organization record** with you as the owner
2. **Activates a FREE subscription** for immediate use
3. **Creates your membership** with the OWNER role
4. **Sets up Stripe billing** for future upgrades

## After Creation

Once your organization is created, you can:

### Invite Team Members

Add collaborators with appropriate roles:

* Go to **Members** in the sidebar
* Click **Invite Member**
* Enter their email and select a role

### Create API Keys

Generate keys for programmatic access:

* Go to **API Keys** in the sidebar
* Click **Create API Key**
* Copy and securely store the key

### Set Up Policies

Define wallet permissions:

* Go to **Policies** in the sidebar
* Create signers and permissions
* Combine them into policies

### Upgrade Your Subscription

Access more features:

* Go to **Billing** in the sidebar
* Choose a plan (PRO, ULTRA, or ENTERPRISE)
* Complete the payment process

## Organization Limits

### FREE Tier Limits

| Resource   | Limit         |
| ---------- | ------------- |
| API Keys   | 1             |
| Team Seats | 1             |
| Paymasters | Not available |

### Paid Tier Limits

| Resource   | PRO       | ULTRA     | ENTERPRISE |
| ---------- | --------- | --------- | ---------- |
| API Keys   | Unlimited | Unlimited | Unlimited  |
| Team Seats | Limited   | Limited   | Unlimited  |
| Paymasters | Yes       | Yes       | Yes        |

## Multiple Organizations

You can create and manage multiple organizations:

### Use Cases

* **Separate projects** - Keep different products isolated
* **Client work** - Maintain separate billing per client
* **Environments** - Split development and production

### Switching Organizations

1. Click the organization dropdown in the sidebar
2. Select the organization you want to switch to
3. The dashboard updates to show that organization's resources

## Organization Settings

After creation, you can configure:

### General Settings

* **Name** - Update the organization name
* **Policy Admin** - Set a Solana public key for admin authority

### Danger Zone

* **Delete Organization** - Permanently remove the organization
  * Only owners can delete
  * This action cannot be undone
  * All resources (API keys, policies, paymasters) are deleted

<Warning>
  Deleting an organization is permanent. Make sure to export any data you need before deletion.
</Warning>

## Troubleshooting

### "Email not verified" Error

If you see this error when creating an organization:

1. Check your inbox for the verification email
2. Click the verification link
3. Try creating the organization again

### Organization Not Appearing

If your new organization doesn't appear:

1. Refresh the page
2. Check the organization dropdown
3. Log out and log back in

## Next Steps

Now that you have an organization:

* [Invite team members](./manage-members) to collaborate
* [Create an API key](./create-api-key) for programmatic access
* [Set up policies](./create-policy) for wallet permissions
* [Upgrade your subscription](./subscriptions-billing) for more features


# Creating a Paymaster
Source: https://build.onswig.com/examples/dev-portal/create-paymaster

"A well-configured paymaster is a happy paymaster" - Swig Operations

This guide walks you through creating a paymaster in the Swig Developer Portal.

## Prerequisites

Before creating a paymaster, ensure you have:

* A **paid subscription** (PRO, ULTRA, or ENTERPRISE)
* Access to the Developer Portal
* SOL to fund the paymaster

<Warning>
  Paymasters are not available on the FREE tier. Upgrade your subscription to access paymaster features.
</Warning>

## Creating a Paymaster

### Step 1: Navigate to Paymasters

1. Log in to the [Developer Portal](https://dashboard.onswig.com)
2. Select your organization
3. Click **Paymaster** in the sidebar

### Step 2: Create New Paymaster

1. Click **Create Paymaster**
2. Configure the settings (see below)
3. Click **Create**

### Step 3: Configure Settings

#### Label (Optional)

A display name for your paymaster:

* Default: `Paymaster {first4}...{last4}` of the public key
* Use descriptive names like `production-mainnet` or `dev-testing`
* Maximum 64 characters

#### Usage API Threshold

Maximum API calls per month:

* Default: 1,000
* Minimum: 1
* Prevents excessive API usage

#### SOL Usage Threshold

Maximum SOL to spend per month:

* Default: 10 SOL (10,000,000,000 lamports)
* Minimum: 0.000000001 SOL
* Controls monthly spending

#### Single TX Limit

Maximum SOL per single transaction:

* Default: 0.1 SOL (100,000,000 lamports)
* Minimum: 0.000000001 SOL
* Prevents large individual transactions

#### Allow Other Instructions

Whether to sponsor non-Swig instructions:

* Default: `false`
* Set to `true` to sponsor any transaction type
* Use with caution (increases potential for abuse)

### Step 4: Paymaster Created

After creation, you'll see:

* **Public Key** - The paymaster's Solana address
* **Label** - Your configured display name
* **Balance** - Current SOL balance (starts at 0)

## Funding Your Paymaster

After creation, your paymaster needs SOL to sponsor transactions.

### Get the Address

1. Go to the Paymaster page
2. Find your paymaster in the list
3. Copy the **Public Key** (Solana address)

### Send SOL

Transfer SOL to the paymaster address:

**Using Solana CLI:**

```bash theme={null}
solana transfer <PAYMASTER_ADDRESS> <AMOUNT> --allow-unfunded-recipient
```

**Using a Wallet:**

1. Open your Solana wallet (Phantom, Solflare, etc.)
2. Send SOL to the paymaster address
3. Wait for confirmation

### Verify Balance

1. Return to the Developer Portal
2. View the paymaster's balance
3. The balance updates after blockchain confirmation

## Example Configuration

### Development Paymaster

For testing on devnet:

| Setting             | Value         | Reason                          |
| ------------------- | ------------- | ------------------------------- |
| Label               | `dev-testing` | Clear purpose                   |
| Usage API Threshold | 100           | Low for testing                 |
| SOL Usage Threshold | 1 SOL         | Conservative limit              |
| Single TX Limit     | 0.01 SOL      | Prevent large test transactions |
| Allow Other Ixs     | `true`        | Flexibility for testing         |

### Production Paymaster

For mainnet applications:

| Setting             | Value                | Reason                  |
| ------------------- | -------------------- | ----------------------- |
| Label               | `production-mainnet` | Clear purpose           |
| Usage API Threshold | 10,000               | Higher for production   |
| SOL Usage Threshold | 100 SOL              | Match expected usage    |
| Single TX Limit     | 0.1 SOL              | Reasonable per-tx limit |
| Allow Other Ixs     | `false`              | Security first          |

## Using Your Paymaster

### Get the Public Key

You'll need the paymaster public key for API calls:

```typescript theme={null}
// The paymaster address is shown in the portal
const paymasterPubkey = 'YourPaymasterPublicKeyHere...';
```

### Create Wallets with Paymaster

Use the paymaster when creating Swig wallets:

```typescript theme={null}
import { SwigApiClient } from '@swig-wallet/api';

const client = new SwigApiClient({
  apiKey: 'sk_your_api_key',
  portalUrl: 'https://dashboard.onswig.com',
});

const { data: wallet, error } = await client.wallet.create({
  policyId: 'your-policy-id',
  network: 'devnet',
  paymasterPubkey: 'YourPaymasterPublicKey',
});
```

### Sponsor Transactions

Use the paymaster to sponsor transactions:

```typescript theme={null}
import { createPaymasterClient } from '@swig-wallet/paymaster-classic';

const paymaster = createPaymasterClient({
  apiKey: 'sk_your_api_key',
  paymasterPubkey: 'YourPaymasterPublicKey',
  baseUrl: 'https://api.onswig.com',
  network: 'devnet',
});

// Create a sponsored transaction
const tx = await paymaster.createLegacyTransaction(
  [yourInstruction],
  [userKeypair]
);

// Sign and send (paymaster covers the fee)
const signature = await paymaster.signAndSend(tx);
```

## Tier Limits

Your subscription tier limits how many paymasters you can create:

| Tier       | Paymasters Allowed |
| ---------- | ------------------ |
| FREE       | 0                  |
| PRO        | Limited            |
| ULTRA      | More               |
| ENTERPRISE | Unlimited          |

Check your subscription status if you hit the limit.

## Multiple Paymasters

Consider creating multiple paymasters for:

### Different Environments

* `dev-devnet` - Development testing
* `staging-devnet` - Staging environment
* `production-mainnet` - Live application

### Different Use Cases

* `user-onboarding` - New user transactions
* `high-value-ops` - Large transactions (higher limits)
* `automated-tasks` - Scheduled operations

### Cost Tracking

* Separate paymasters per product/feature
* Easier to attribute costs
* Better usage visibility

## Troubleshooting

### "Subscription required" Error

You need a paid subscription:

1. Go to **Billing** in the sidebar
2. Upgrade to PRO or higher
3. Try creating the paymaster again

### "Paymaster limit reached" Error

You've hit your tier's paymaster limit:

1. Check your current paymaster count
2. Delete unused paymasters
3. Or upgrade your subscription

### Paymaster Balance is 0

The paymaster needs funding:

1. Copy the paymaster's public key
2. Send SOL to that address
3. Wait for blockchain confirmation

## Next Steps

* [Manage paymaster settings](./manage-paymaster)
* [View transaction history](./transaction-history)
* [Monitor usage and analytics](./transaction-history)


# Creating a Policy
Source: https://build.onswig.com/examples/dev-portal/create-policy

"A good policy is worth a thousand lines of code" - Swig Protocol

Policies define how Swig wallets are created and what permissions they have. This guide explains the concepts behind policies and walks you through creating one in the Developer Portal.

## Understanding Policies

A **Policy** combines two key components:

* **Signer**: The cryptographic identity (authority) that controls the wallet
* **Permission**: The set of allowed actions for that signer

```
Policy = Signer + Permission
```

When you create a Swig wallet using a policy, the wallet is initialized with the signer and permissions defined in that policy.

<Tip>
  Policies can be created without a signer. In this case, you must provide the signer information when creating a wallet via the API.
</Tip>

## Key Concepts

### Signers

A **Signer** represents a cryptographic authority that can sign transactions for the wallet. Each signer has:

* **Type**: The signature algorithm used
* **Public Key**: The cryptographic public key
* **Max Duration Slots** (for sessions): How long the authority remains valid

### Permissions

A **Permission** defines what actions a signer can perform. Permissions are composed of one or more **Actions** that specify allowed operations.

### Authority Types

Swig supports multiple authority types for different use cases:

| Type                | Description                 | Use Case                            |
| ------------------- | --------------------------- | ----------------------------------- |
| `ED25519`           | Standard Solana keypair     | Most common, native Solana wallets  |
| `ED25519_SESSION`   | Time-limited Ed25519        | Temporary access, delegated signing |
| `SECP256K1`         | Ethereum-compatible keys    | Cross-chain, Ethereum wallet users  |
| `SECP256K1_SESSION` | Time-limited Secp256k1      | Temporary Ethereum key access       |
| `SECP256R1`         | WebAuthn/Passkey compatible | Browser-based authentication        |
| `SECP256R1_SESSION` | Time-limited Secp256r1      | Temporary passkey sessions          |

### Action Types

Actions define what operations are permitted:

**General:**

* `All` - Full access to all operations
* `AllButManageAuthority` - Everything except adding/removing signers
* `ManageAuthority` - Can add and remove signers

**SOL Transfers:**

* `SolLimit` - Transfer up to a specified amount of SOL
* `SolRecurringLimit` - Transfer up to an amount within a time window
* `SolDestinationLimit` - Transfer to a specific destination only
* `SolRecurringDestinationLimit` - Recurring limit to specific destination

**Token Transfers:**

* `TokenLimit` - Transfer up to a specified amount of a token
* `TokenRecurringLimit` - Token transfer with time-based limits
* `TokenDestinationLimit` - Token transfer to specific destination
* `TokenRecurringDestinationLimit` - Recurring token limit to destination

**Program Access:**

* `Program` - Can interact with a specific program ID
* `ProgramAll` - Can interact with any program
* `ProgramCurated` - Can interact with curated/approved programs

**Staking:**

* `StakeLimit` - Stake up to a specified amount
* `StakeRecurringLimit` - Staking with time-based limits
* `StakeAll` - Full staking permissions

**Sub-accounts:**

* `SubAccount` - Can manage sub-accounts

## Creating a Policy

### Step 1: Navigate to Policies

1. Log in to the [Developer Portal](https://dashboard.onswig.com)
2. Select your project
3. Click **Policies** in the navigation menu

### Step 2: Start Policy Creation

Click the **Create Policy** button to open the policy creation dialog.

### Step 3: Select or Create a Permission

The first step asks you to choose permissions:

**Option A: Use an Existing Permission**

* Search and select from your previously created permissions
* Useful for reusing permission sets across multiple policies

**Option B: Start from a Template**

* **Blank**: Start with no actions (add your own)
* **Full Access**: Includes the `All` action
* Other templates may be available

**Option C: Create a New Permission**

* Configure custom actions for this policy
* The permission is saved and can be reused later

### Step 4: Configure the Policy

Fill in the policy details:

#### Basic Information

* **Policy Name** (required): A descriptive name, e.g., `user-wallet-policy`
* **Description** (optional): Explain the policy's purpose

#### Signer Configuration

Choose one of three options:

**Link Existing Signer:**

* Select from signers you've previously created
* Useful for reusing the same authority across policies

**Create New Signer:**

* **Signer Name**: Descriptive name for the signer
* **Type**: Select the authority type (Ed25519, Secp256k1, etc.)
* **Public Key**: The authority's public key
  * For Ed25519: Base58-encoded public key
  * For Secp256k1/Secp256r1: Hex-encoded (64 bytes)
* **Max Duration Slots** (session types only): How long the session is valid

**Skip for Now:**

* Create the policy without a signer
* You must provide the signer when creating wallets via the API

#### Permission Configuration

If you didn't select an existing permission:

* Use the **Permissions Builder** to add actions
* Configure limits and destinations as needed
* At least one action is required

### Step 5: Create the Policy

Review your configuration and click **Create Policy**.

## Policy Status

Policies have different statuses based on their configuration:

| Status                 | Meaning                               |
| ---------------------- | ------------------------------------- |
| **Complete**           | Has both signer and permission        |
| **Missing Signer**     | Has permission but no signer attached |
| **Missing Permission** | Has signer but no permission (rare)   |
| **Incomplete**         | Missing both signer and permission    |

<Tip>
  Policies with "Missing Signer" status can still be used. Provide the signer information when creating a wallet via the API's `signerId` parameter.
</Tip>

## Example: Creating a Limited Transfer Policy

Here's an example of creating a policy that allows limited SOL transfers:

1. **Policy Name**: `limited-sol-transfer`
2. **Description**: `Allows up to 1 SOL transfers per day`
3. **Signer**:
   * Type: `ED25519`
   * Public Key: Your user's Solana public key
4. **Permission Actions**:
   * `SolRecurringLimit`:
     * Amount: `1000000000` (1 SOL in lamports)
     * Window: `86400` (24 hours in seconds)

This policy creates wallets where the signer can transfer up to 1 SOL per day.

## Managing Policies

### Viewing Policies

The Policies page shows:

* Policy name and description
* Attached signer (if any)
* Permission summary
* Status indicator
* Last updated timestamp

### Updating Policies

Click on a policy to:

* Change the name or description
* Attach a different signer
* Update the permission

### Deleting Policies

<Warning>
  Deleting a policy does not affect wallets already created with it. Existing wallets retain their original configuration.
</Warning>

## Next Steps

Now that you've created a policy, you can:

* [Fetch the policy](./fetch-policy) via the API to verify its configuration
* [Create Swig wallets](./create-swig) using your policy


# Creating a Swig Wallet
Source: https://build.onswig.com/examples/dev-portal/create-swig

"Every great wallet starts with a single transaction" - Swig Founders

This guide shows how to create Swig wallets programmatically using the Developer Portal API. This approach is ideal for applications that need to create wallets on behalf of users with predefined policies.

## When to Use the API

**Use the Portal API when:**

* Creating wallets from a backend service
* Using predefined policies from the Developer Portal
* Leveraging the paymaster for sponsored wallet creation
* Managing wallets at scale

**Use the SDK directly when:**

* Building client-side applications
* Users control their own keypairs
* You need full control over wallet configuration
* Not using the Developer Portal policies

<Tip>
  For direct SDK wallet creation (without the Portal API), see the [Creating a Swig tutorial](/tutorials/typescript/create).
</Tip>

## Prerequisites

Before creating wallets via the API, ensure you have:

* An [API key](./create-api-key) created in the Developer Portal
* A [policy](./create-policy) configured (with or without a signer)
* The paymaster public key (provided by Swig or your own paymaster)

## Installing the SDK

<Tabs>
  <Tab title="API SDK">
    ```bash theme={null}
    npm install @swig-wallet/api
    # or
    bun add @swig-wallet/api
    ```
  </Tab>

  <Tab title="Developer SDK">
    ```bash theme={null}
    npm install @swig-wallet/developer
    # or
    bun add @swig-wallet/developer
    ```
  </Tab>
</Tabs>

## Creating a Swig Wallet

### Using the REST API

Make a POST request to the wallet creation endpoint:

```bash theme={null}
curl -X POST "https://dashboard.onswig.com/api/v1/wallet/create" \
  -H "Authorization: Bearer sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "policyId": "clx1234567890abcdef",
    "network": "devnet",
    "paymasterPubkey": "PaymasterPublicKeyHere..."
  }'
```

**Example Response:**

```json theme={null}
{
  "swigId": "a1b2c3d4e5f67890",
  "swigAddress": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
  "signature": "5wHu1qwD7g4p3zWxF..."
}
```

### Using the SDK

<Tabs>
  <Tab title="API SDK">
    ```typescript theme={null}
    import { SwigApiClient } from '@swig-wallet/api';

    // Initialize the client
    const client = new SwigApiClient({
      apiKey: 'sk_your_api_key',
      portalUrl: 'https://dashboard.onswig.com',
    });

    // Create a wallet
    async function createWallet() {
      const { data: wallet, error } = await client.wallet.create({
        policyId: 'clx1234567890abcdef',
        network: 'devnet',
        paymasterPubkey: 'PaymasterPublicKeyHere...',
      });

      if (error) {
        console.error(`Error creating wallet: ${error.message}`);
        return null;
      }

      console.log('Swig ID:', wallet.swigId);
      console.log('Wallet Address:', wallet.swigAddress);
      console.log('Transaction Signature:', wallet.signature);

      return wallet;
    }

    const wallet = await createWallet();
    ```
  </Tab>

  <Tab title="Developer SDK">
    ```typescript theme={null}
    import { SwigClient, SwigError } from '@swig-wallet/developer';

    // Initialize the client
    const client = new SwigClient({
      apiKey: 'sk_your_api_key',
      baseUrl: 'https://dashboard.onswig.com',
    });

    // Create a wallet
    async function createWallet() {
      try {
        const wallet = await client.createWallet({
          policyId: 'clx1234567890abcdef',
          network: 'devnet',
          paymasterPubkey: 'PaymasterPublicKeyHere...',
        });

        console.log('Swig ID:', wallet.swigId);
        console.log('Wallet Address:', wallet.swigAddress);
        console.log('Transaction Signature:', wallet.signature);

        return wallet;
      } catch (error) {
        if (error instanceof SwigError) {
          console.error(`Error: ${error.code} - ${error.message}`);
        }
        return null;
      }
    }

    const wallet = await createWallet();
    ```
  </Tab>
</Tabs>

## SDK Comparison

| Feature        | @swig-wallet/api          | @swig-wallet/developer  |
| -------------- | ------------------------- | ----------------------- |
| Error handling | Returns `{ data, error }` | Throws `SwigError`      |
| Method name    | `client.wallet.create()`  | `client.createWallet()` |
| Response type  | Basic object              | Same basic object       |
| Best for       | Low-level control         | Developer convenience   |

## Request Parameters

### Required Parameters

| Parameter         | Type                      | Description                               |
| ----------------- | ------------------------- | ----------------------------------------- |
| `policyId`        | string                    | The policy ID from the Developer Portal   |
| `network`         | `'mainnet'` \| `'devnet'` | Target Solana network                     |
| `paymasterPubkey` | string                    | Public key of the paymaster covering fees |

### Optional Parameters

| Parameter  | Type   | Description                                             |
| ---------- | ------ | ------------------------------------------------------- |
| `swigId`   | string | Custom Swig ID (auto-generated if not provided)         |
| `signerId` | string | Override or provide signer ID when policy has no signer |

## Response Fields

| Field         | Type   | Description                                      |
| ------------- | ------ | ------------------------------------------------ |
| `swigId`      | string | The 8-byte identifier for this Swig wallet       |
| `swigAddress` | string | The on-chain PDA address of the wallet           |
| `signature`   | string | The transaction signature (viewable on explorer) |

## Examples

### Basic Wallet Creation

<Tabs>
  <Tab title="API SDK">
    ```typescript theme={null}
    import { SwigApiClient } from '@swig-wallet/api';

    const client = new SwigApiClient({
      apiKey: process.env.SWIG_API_KEY!,
      portalUrl: 'https://dashboard.onswig.com',
    });

    const { data, error } = await client.wallet.create({
      policyId: 'your-policy-id',
      network: 'devnet',
      paymasterPubkey: 'YourPaymasterPublicKey',
    });

    if (data) {
      console.log(`Wallet created: ${data.swigAddress}`);
      console.log(`View on explorer: https://explorer.solana.com/address/${data.swigAddress}?cluster=devnet`);
    }
    ```
  </Tab>

  <Tab title="Developer SDK">
    ```typescript theme={null}
    import { SwigClient } from '@swig-wallet/developer';

    const client = new SwigClient({
      apiKey: process.env.SWIG_API_KEY!,
      baseUrl: 'https://dashboard.onswig.com',
    });

    const wallet = await client.createWallet({
      policyId: 'your-policy-id',
      network: 'devnet',
      paymasterPubkey: 'YourPaymasterPublicKey',
    });

    console.log(`Wallet created: ${wallet.swigAddress}`);
    console.log(`View on explorer: https://explorer.solana.com/address/${wallet.swigAddress}?cluster=devnet`);
    ```
  </Tab>
</Tabs>

### With Custom Swig ID

<Tabs>
  <Tab title="API SDK">
    ```typescript theme={null}
    // Generate a custom ID (must be unique)
    const customId = crypto.randomUUID().replace(/-/g, '').slice(0, 16);

    const { data, error } = await client.wallet.create({
      policyId: 'your-policy-id',
      network: 'devnet',
      paymasterPubkey: 'YourPaymasterPublicKey',
      swigId: customId,
    });
    ```
  </Tab>

  <Tab title="Developer SDK">
    ```typescript theme={null}
    // Generate a custom ID (must be unique)
    const customId = crypto.randomUUID().replace(/-/g, '').slice(0, 16);

    const wallet = await client.createWallet({
      policyId: 'your-policy-id',
      network: 'devnet',
      paymasterPubkey: 'YourPaymasterPublicKey',
      swigId: customId,
    });
    ```
  </Tab>
</Tabs>

### With Signer Override

If your policy doesn't have a signer attached, or you want to use a different signer:

<Tabs>
  <Tab title="API SDK">
    ```typescript theme={null}
    const { data, error } = await client.wallet.create({
      policyId: 'policy-without-signer',
      network: 'devnet',
      paymasterPubkey: 'YourPaymasterPublicKey',
      signerId: 'specific-signer-id', // Signer ID from the portal
    });
    ```
  </Tab>

  <Tab title="Developer SDK">
    ```typescript theme={null}
    const wallet = await client.createWallet({
      policyId: 'policy-without-signer',
      network: 'devnet',
      paymasterPubkey: 'YourPaymasterPublicKey',
      signerId: 'specific-signer-id', // Signer ID from the portal
    });
    ```
  </Tab>
</Tabs>

### Production Wallet

<Tabs>
  <Tab title="API SDK">
    ```typescript theme={null}
    const { data, error } = await client.wallet.create({
      policyId: 'production-policy-id',
      network: 'mainnet', // Use mainnet for production
      paymasterPubkey: 'ProductionPaymasterKey',
    });

    if (data) {
      // Store the wallet info in your database
      await db.wallets.create({
        swigId: data.swigId,
        address: data.swigAddress,
        createdAt: new Date(),
      });
    }
    ```
  </Tab>

  <Tab title="Developer SDK">
    ```typescript theme={null}
    const wallet = await client.createWallet({
      policyId: 'production-policy-id',
      network: 'mainnet', // Use mainnet for production
      paymasterPubkey: 'ProductionPaymasterKey',
    });

    // Store the wallet info in your database
    await db.wallets.create({
      swigId: wallet.swigId,
      address: wallet.swigAddress,
      createdAt: new Date(),
    });
    ```
  </Tab>
</Tabs>

## Error Handling

<Tabs>
  <Tab title="API SDK">
    ```typescript theme={null}
    const { data, error } = await client.wallet.create({
      policyId: 'your-policy-id',
      network: 'devnet',
      paymasterPubkey: 'YourPaymasterPublicKey',
    });

    if (error) {
      switch (error.code) {
        case 'NOT_FOUND':
          console.error('Policy not found. Check the policy ID.');
          break;
        case 'UNAUTHORIZED':
          console.error('Invalid API key.');
          break;
        case 'BAD_REQUEST':
          console.error('Invalid request:', error.details);
          break;
        case 'CONFLICT':
          console.error('Swig ID already exists. Try a different ID.');
          break;
        default:
          console.error(`Unexpected error: ${error.message}`);
      }
    }
    ```
  </Tab>

  <Tab title="Developer SDK">
    ```typescript theme={null}
    try {
      const wallet = await client.createWallet({
        policyId: 'your-policy-id',
        network: 'devnet',
        paymasterPubkey: 'YourPaymasterPublicKey',
      });
    } catch (error) {
      if (error instanceof SwigError) {
        switch (error.code) {
          case 'POLICY_NOT_FOUND':
            console.error('Policy not found. Check the policy ID.');
            break;
          case 'UNAUTHORIZED':
            console.error('Invalid API key.');
            break;
          case 'BAD_REQUEST':
            console.error('Invalid request:', error.response);
            break;
          case 'SWIG_ID_EXISTS':
            console.error('Swig ID already exists. Try a different ID.');
            break;
          default:
            console.error(`Unexpected error: ${error.message}`);
        }
      }
    }
    ```
  </Tab>
</Tabs>

### Common Errors

| Status | Code                             | Meaning                    |
| ------ | -------------------------------- | -------------------------- |
| 400    | `BAD_REQUEST`                    | Invalid request parameters |
| 401    | `UNAUTHORIZED`                   | Invalid or missing API key |
| 404    | `NOT_FOUND` / `POLICY_NOT_FOUND` | Policy or signer not found |
| 409    | `CONFLICT` / `SWIG_ID_EXISTS`    | Swig ID already exists     |
| 500    | `INTERNAL_ERROR`                 | Server error, try again    |

## Complete Example

<Tabs>
  <Tab title="API SDK">
    ```typescript theme={null}
    import { SwigApiClient } from '@swig-wallet/api';

    async function main() {
      const client = new SwigApiClient({
        apiKey: process.env.SWIG_API_KEY!,
        portalUrl: 'https://dashboard.onswig.com',
        retry: { maxRetries: 3, retryDelay: 1000 },
      });

      const config = {
        policyId: process.env.SWIG_POLICY_ID!,
        network: (process.env.SWIG_NETWORK || 'devnet') as 'mainnet' | 'devnet',
        paymasterPubkey: process.env.SWIG_PAYMASTER_PUBKEY!,
      };

      console.log('Creating Swig wallet...');
      console.log(`Network: ${config.network}`);
      console.log(`Policy: ${config.policyId}`);

      const { data: wallet, error } = await client.wallet.create(config);

      if (error) {
        console.error('Failed to create wallet:', error.message);
        console.error('Error code:', error.code);
        process.exit(1);
      }

      console.log('\n=== Wallet Created ===');
      console.log(`Swig ID: ${wallet.swigId}`);
      console.log(`Address: ${wallet.swigAddress}`);
      console.log(`Transaction: ${wallet.signature}`);

      const cluster = config.network === 'mainnet' ? '' : '?cluster=devnet';
      console.log(`\nExplorer: https://explorer.solana.com/address/${wallet.swigAddress}${cluster}`);
    }

    main();
    ```
  </Tab>

  <Tab title="Developer SDK">
    ```typescript theme={null}
    import { SwigClient, SwigError } from '@swig-wallet/developer';

    async function main() {
      const client = new SwigClient({
        apiKey: process.env.SWIG_API_KEY!,
        baseUrl: 'https://dashboard.onswig.com',
        retryOptions: { maxRetries: 3, retryDelay: 1000 },
      });

      const config = {
        policyId: process.env.SWIG_POLICY_ID!,
        network: (process.env.SWIG_NETWORK || 'devnet') as 'mainnet' | 'devnet',
        paymasterPubkey: process.env.SWIG_PAYMASTER_PUBKEY!,
      };

      console.log('Creating Swig wallet...');
      console.log(`Network: ${config.network}`);
      console.log(`Policy: ${config.policyId}`);

      try {
        const wallet = await client.createWallet(config);

        console.log('\n=== Wallet Created ===');
        console.log(`Swig ID: ${wallet.swigId}`);
        console.log(`Address: ${wallet.swigAddress}`);
        console.log(`Transaction: ${wallet.signature}`);

        const cluster = config.network === 'mainnet' ? '' : '?cluster=devnet';
        console.log(`\nExplorer: https://explorer.solana.com/address/${wallet.swigAddress}${cluster}`);
      } catch (error) {
        if (error instanceof SwigError) {
          console.error('Failed to create wallet:', error.message);
          console.error('Error code:', error.code);
          process.exit(1);
        }
        throw error;
      }
    }

    main();
    ```
  </Tab>
</Tabs>

## TypeScript Types

```typescript theme={null}
interface CreateWalletRequest {
  /** Policy ID to use for wallet creation */
  policyId: string;
  /** Optional signer ID to override or provide */
  signerId?: string;
  /** Optional swig ID (generated if not provided) */
  swigId?: string;
  /** Network to use */
  network: 'mainnet' | 'devnet';
  /** Paymaster public key */
  paymasterPubkey: string;
}

interface CreateWalletResponse {
  /** Swig ID (8-byte identifier) */
  swigId: string;
  /** Swig wallet address */
  swigAddress: string;
  /** Transaction signature */
  signature: string;
}
```

## Comparison: API vs Direct SDK

| Feature                    | Portal API        | Direct SDK  |
| -------------------------- | ----------------- | ----------- |
| Uses predefined policies   | Yes               | No          |
| Requires API key           | Yes               | No          |
| Paymaster sponsored        | Yes               | Optional    |
| Full configuration control | Limited to policy | Full        |
| Best for                   | Backend services  | Client apps |
| Keypair management         | Server-side       | Client-side |

## Next Steps

After creating a wallet, you can:

* View the wallet on [Solana Explorer](https://explorer.solana.com)
* [Sign transactions](/tutorials/typescript/sign) using the wallet
* [Manage authorities](/tutorials/typescript/managing_authorities) to add more signers


# Error Codes & Troubleshooting
Source: https://build.onswig.com/examples/dev-portal/error-codes

"Every error is a lesson in disguise" - Swig Debugging

This guide covers common errors, their causes, and how to resolve them when using the Swig Developer Portal API.

## HTTP Status Codes

| Status | Name                  | Description                     |
| ------ | --------------------- | ------------------------------- |
| 200    | OK                    | Request succeeded               |
| 201    | Created               | Resource created successfully   |
| 400    | Bad Request           | Invalid request parameters      |
| 401    | Unauthorized          | Invalid or missing API key      |
| 403    | Forbidden             | No access to the resource       |
| 404    | Not Found             | Resource doesn't exist          |
| 409    | Conflict              | Resource already exists         |
| 429    | Too Many Requests     | Rate limit exceeded             |
| 500    | Internal Server Error | Server error                    |
| 503    | Service Unavailable   | Service temporarily unavailable |

## Error Response Format

All API errors follow this format:

```json theme={null}
{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description",
    "details": {
      "field": "Additional context"
    }
  }
}
```

## Common Error Codes

### Authentication Errors

#### UNAUTHORIZED

```json theme={null}
{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  }
}
```

**Causes:**

* Missing `Authorization` header
* Invalid API key format
* Expired API key
* Revoked API key

**Solutions:**

1. Check the `Authorization` header is set correctly:
   ```
   Authorization: Bearer sk_your_api_key
   ```
2. Verify the API key in the Developer Portal
3. Generate a new API key if needed

***

#### FORBIDDEN

```json theme={null}
{
  "error": {
    "code": "FORBIDDEN",
    "message": "You do not have access to this resource"
  }
}
```

**Causes:**

* API key doesn't have access to the organization
* Attempting to access another organization's resources

**Solutions:**

1. Verify you're using the correct API key
2. Check the resource belongs to your organization

***

### Resource Errors

#### NOT\_FOUND / POLICY\_NOT\_FOUND

```json theme={null}
{
  "error": {
    "code": "POLICY_NOT_FOUND",
    "message": "Policy not found"
  }
}
```

**Causes:**

* Policy ID doesn't exist
* Policy was deleted
* Typo in the policy ID

**Solutions:**

1. Verify the policy ID in the Developer Portal
2. Check for typos (IDs are case-sensitive)
3. Confirm the policy hasn't been deleted

***

#### SWIG\_ID\_EXISTS / CONFLICT

```json theme={null}
{
  "error": {
    "code": "CONFLICT",
    "message": "A Swig with this ID already exists"
  }
}
```

**Causes:**

* Duplicate custom Swig ID
* Retry with same ID after successful creation

**Solutions:**

1. Use a unique Swig ID
2. Omit `swigId` for auto-generation
3. Check if the wallet was already created

***

### Validation Errors

#### BAD\_REQUEST

```json theme={null}
{
  "error": {
    "code": "BAD_REQUEST",
    "message": "Invalid request parameters",
    "details": {
      "policyId": "Policy ID is required",
      "network": "Must be 'mainnet' or 'devnet'"
    }
  }
}
```

**Causes:**

* Missing required fields
* Invalid field values
* Malformed JSON

**Solutions:**

1. Check all required fields are provided
2. Validate field formats and values
3. Ensure valid JSON in request body

***

#### MISSING\_URL

```json theme={null}
{
  "error": {
    "code": "MISSING_URL",
    "message": "Portal URL is required for this operation"
  }
}
```

**Causes:**

* SDK not configured with portal URL

**Solutions:**

```typescript theme={null}
const client = new SwigApiClient({
  apiKey: 'sk_your_api_key',
  portalUrl: 'https://dashboard.onswig.com', // Add this
});
```

***

### Rate Limit Errors

#### RATE\_LIMITED

```json theme={null}
{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Too many requests. Please retry after 60 seconds"
  }
}
```

**Causes:**

* Exceeded requests per minute
* Burst of requests

**Solutions:**

1. Implement exponential backoff
2. Reduce request frequency
3. Upgrade subscription for higher limits

***

### Paymaster Errors

#### INSUFFICIENT\_BALANCE

```json theme={null}
{
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Paymaster has insufficient balance"
  }
}
```

**Causes:**

* Paymaster wallet has no SOL
* Transaction fee exceeds available balance

**Solutions:**

1. Fund the paymaster wallet
2. Reduce transaction complexity

***

#### LIMIT\_EXCEEDED

```json theme={null}
{
  "error": {
    "code": "LIMIT_EXCEEDED",
    "message": "Monthly limit exceeded"
  }
}
```

**Causes:**

* Exceeded SOL usage threshold
* Exceeded API call threshold
* Exceeded subscription limit

**Solutions:**

1. Wait for monthly reset
2. Increase paymaster limits
3. Upgrade subscription

***

#### SINGLE\_TX\_LIMIT\_EXCEEDED

```json theme={null}
{
  "error": {
    "code": "SINGLE_TX_LIMIT_EXCEEDED",
    "message": "Transaction exceeds single transaction limit"
  }
}
```

**Causes:**

* Transaction fee exceeds per-transaction limit

**Solutions:**

1. Increase single TX limit in paymaster settings
2. Simplify the transaction

***

### Subscription Errors

#### SUBSCRIPTION\_REQUIRED

```json theme={null}
{
  "error": {
    "code": "SUBSCRIPTION_REQUIRED",
    "message": "This feature requires a paid subscription"
  }
}
```

**Causes:**

* Attempting to use paymaster on FREE tier
* Feature requires upgrade

**Solutions:**

1. Upgrade to PRO or higher
2. Use free tier features only

***

## SDK Error Handling

### API SDK (@swig-wallet/api)

```typescript theme={null}
import { SwigApiClient, ApiError } from '@swig-wallet/api';

const client = new SwigApiClient({
  apiKey: process.env.SWIG_API_KEY!,
  portalUrl: 'https://dashboard.onswig.com',
});

const { data, error } = await client.policies.get(policyId);

if (error) {
  // error is an ApiError
  console.error('Error code:', error.code);
  console.error('Status:', error.status);
  console.error('Message:', error.message);
  console.error('Details:', error.details);

  switch (error.code) {
    case 'NOT_FOUND':
      // Handle missing resource
      break;
    case 'UNAUTHORIZED':
      // Handle auth error
      break;
    case 'RATE_LIMITED':
      // Implement backoff
      break;
    default:
      // Handle unexpected error
  }
}
```

### Developer SDK (@swig-wallet/developer)

```typescript theme={null}
import { SwigClient, SwigError } from '@swig-wallet/developer';

const client = new SwigClient({
  apiKey: process.env.SWIG_API_KEY!,
  baseUrl: 'https://dashboard.onswig.com',
});

try {
  const policy = await client.getPolicy(policyId);
} catch (error) {
  if (error instanceof SwigError) {
    // error is a SwigError
    console.error('Error code:', error.code);
    console.error('Status:', error.statusCode);
    console.error('Message:', error.message);
    console.error('Response:', error.response);

    switch (error.code) {
      case 'POLICY_NOT_FOUND':
        // Handle missing policy
        break;
      case 'UNAUTHORIZED':
        // Handle auth error
        break;
      default:
        // Handle unexpected error
    }
  } else {
    // Handle non-API errors
    throw error;
  }
}
```

## Retry Strategies

### Exponential Backoff

For transient errors (5xx, network issues):

```typescript theme={null}
async function fetchWithRetry<T>(
  fn: () => Promise<T>,
  maxRetries = 3,
  baseDelay = 1000
): Promise<T> {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (i === maxRetries - 1) throw error;

      const delay = baseDelay * Math.pow(2, i);
      await new Promise(resolve => setTimeout(resolve, delay));
    }
  }
  throw new Error('Max retries exceeded');
}
```

### SDK Built-in Retry

Both SDKs support retry configuration:

```typescript theme={null}
// API SDK
const client = new SwigApiClient({
  apiKey: 'sk_your_api_key',
  retry: {
    maxRetries: 3,
    retryDelay: 1000,
    backoffMultiplier: 2,
  },
});

// Developer SDK
const client = new SwigClient({
  apiKey: 'sk_your_api_key',
  retryOptions: {
    maxRetries: 3,
    retryDelay: 1000,
    backoffMultiplier: 2,
  },
});
```

## Debugging Tips

### Enable Logging

Log requests and responses for debugging:

```typescript theme={null}
// Log before request
console.log('Request:', { url, method, body });

// Log response
console.log('Response:', { status, data, error });
```

### Check API Key

Verify your API key is correct:

1. Log in to Developer Portal
2. Go to API Keys
3. Verify the key exists and isn't expired

### Validate Inputs

Before sending requests:

```typescript theme={null}
if (!policyId) {
  throw new Error('Policy ID is required');
}

if (!['mainnet', 'devnet'].includes(network)) {
  throw new Error('Network must be mainnet or devnet');
}
```

### Use Test Environment

Test on devnet first:

```typescript theme={null}
const config = {
  network: 'devnet', // Use devnet for testing
  // ...
};
```

## Getting Help

If you're stuck:

1. **Check this guide** - Most common issues are covered above
2. **Search the docs** - Use the search function
3. **Community support** - Join our [Telegram](https://t.me/onswig)
4. **GitHub issues** - Report bugs at [swig-wallet](https://github.com/anagrambuild/swig-wallet)
5. **Email support** - Paid tiers get email support

When reporting issues, include:

* Error code and message
* Request details (sanitize sensitive data)
* Steps to reproduce
* SDK version


# Fetching Policies
Source: https://build.onswig.com/examples/dev-portal/fetch-policy

"Know your policy, know your wallet" - Swig Developers

Once you've created policies in the Developer Portal, you can fetch their details programmatically. This guide shows how to retrieve policy information using the REST API and TypeScript SDKs.

## Prerequisites

Before fetching policies, ensure you have:

* An [API key](./create-api-key) created in the Developer Portal
* A [policy](./create-policy) created that you want to fetch
* The policy ID (visible in the portal's policy details)

## Installing the SDK

<Tabs>
  <Tab title="API SDK">
    ```bash theme={null}
    npm install @swig-wallet/api
    # or
    bun add @swig-wallet/api
    ```
  </Tab>

  <Tab title="Developer SDK">
    ```bash theme={null}
    npm install @swig-wallet/developer
    # or
    bun add @swig-wallet/developer
    ```
  </Tab>
</Tabs>

## Fetching a Policy

### Using the REST API

Make a GET request to the policies endpoint:

```bash theme={null}
curl -X GET "https://dashboard.onswig.com/api/v1/policies/{policyId}" \
  -H "Authorization: Bearer sk_your_api_key"
```

Replace `{policyId}` with your actual policy ID (e.g., `clx1234567890abcdef`).

**Example Response:**

```json theme={null}
{
  "id": "clx1234567890abcdef",
  "name": "user-wallet-policy",
  "description": "Standard user wallet with transfer limits",
  "authority": {
    "type": "Ed25519",
    "publicKey": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU"
  },
  "actions": [
    { "type": "SolLimit", "amount": "1000000000" },
    { "type": "TokenLimit", "mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", "amount": "1000000" }
  ]
}
```

### Using the SDK

<Tabs>
  <Tab title="API SDK">
    ```typescript theme={null}
    import { SwigApiClient } from '@swig-wallet/api';

    // Initialize the client
    const client = new SwigApiClient({
      apiKey: 'sk_your_api_key',
      portalUrl: 'https://dashboard.onswig.com',
    });

    // Fetch a policy
    async function getPolicy(policyId: string) {
      const { data: policy, error } = await client.policies.get(policyId);

      if (error) {
        console.error(`Error fetching policy: ${error.message}`);
        console.error(`Error code: ${error.code}, Status: ${error.status}`);
        return null;
      }

      console.log('Policy:', policy.name);
      console.log('Description:', policy.description);

      if (policy.authority) {
        console.log('Authority Type:', policy.authority.type);
        console.log('Authority Key:', policy.authority.publicKey);
      } else {
        console.log('Authority: Not configured (provide at wallet creation)');
      }

      console.log('Actions:', policy.actions.map(a => a.type).join(', '));

      return policy;
    }

    // Usage
    const policy = await getPolicy('clx1234567890abcdef');
    ```
  </Tab>

  <Tab title="Developer SDK">
    ```typescript theme={null}
    import { SwigClient, SwigError } from '@swig-wallet/developer';

    // Initialize the client
    const client = new SwigClient({
      apiKey: 'sk_your_api_key',
      baseUrl: 'https://dashboard.onswig.com',
    });

    // Fetch a policy
    async function getPolicy(policyId: string) {
      try {
        const policy = await client.getPolicy(policyId);

        console.log('Policy:', policy.name);

        // Rich authority methods
        if (policy.authority) {
          console.log('Authority Type:', policy.authority.type);

          if (policy.authority.isSession()) {
            console.log('Session Duration:', policy.authority.maxDurationSlots, 'slots');
          }

          if (policy.authority.isEd25519()) {
            console.log('Using Ed25519 signature scheme');
          }
        }

        // Rich action query methods
        if (policy.actions.canSpendSol(1_000_000_000n)) {
          console.log('Can spend up to 1 SOL');
        }

        const solLimit = policy.actions.solSpendLimit();
        if (solLimit) {
          console.log('SOL limit:', solLimit, 'lamports');
        }

        if (policy.actions.canUseProgram('TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA')) {
          console.log('Can interact with Token program');
        }

        return policy;
      } catch (error) {
        if (error instanceof SwigError) {
          console.error(`Error: ${error.code} - ${error.message}`);
        }
        return null;
      }
    }

    // Usage
    const policy = await getPolicy('clx1234567890abcdef');
    ```
  </Tab>
</Tabs>

## SDK Comparison

| Feature        | @swig-wallet/api          | @swig-wallet/developer                                  |
| -------------- | ------------------------- | ------------------------------------------------------- |
| Error handling | Returns `{ data, error }` | Throws `SwigError`                                      |
| Policy type    | Basic `Policy` interface  | Rich `Policy` class with methods                        |
| Authority info | Raw config object         | `AuthorityInfo` with `isSession()`, `isEd25519()`, etc. |
| Actions        | Raw array                 | `Actions` with `canSpendSol()`, `solSpendLimit()`, etc. |
| Best for       | Low-level control         | Developer convenience                                   |

## Response Types

### Policy

```typescript theme={null}
interface Policy {
  /** Unique policy ID */
  id: string;
  /** Policy name */
  name: string;
  /** Optional description */
  description: string | null;
  /** Authority configuration (signer) - null if not configured */
  authority: AuthorityConfig | null;
  /** Action configurations (permissions) */
  actions: ActionConfig[];
}
```

### Authority Configuration

The `authority` field can be one of several types:

```typescript theme={null}
type AuthorityConfig =
  | { type: 'Ed25519'; publicKey: string }
  | { type: 'Ed25519Session'; publicKey: string; maxDurationSlots: string }
  | { type: 'Secp256k1'; publicKey: string }
  | { type: 'Secp256k1Session'; publicKey: string; maxDurationSlots: string }
  | { type: 'Secp256r1'; publicKey: string }
  | { type: 'Secp256r1Session'; publicKey: string; maxDurationSlots: string };
```

### Action Configuration

The `actions` array contains one or more action configurations:

```typescript theme={null}
type ActionConfig =
  // General permissions
  | { type: 'All' }
  | { type: 'AllButManageAuthority' }
  | { type: 'ManageAuthority' }

  // SOL transfer limits
  | { type: 'SolLimit'; amount: string }
  | { type: 'SolRecurringLimit'; recurringAmount: string; window: string }
  | { type: 'SolDestinationLimit'; amount: string; destination: string }
  | { type: 'SolRecurringDestinationLimit'; recurringAmount: string; window: string; destination: string }

  // Token transfer limits
  | { type: 'TokenLimit'; mint: string; amount: string }
  | { type: 'TokenRecurringLimit'; mint: string; recurringAmount: string; window: string }
  | { type: 'TokenDestinationLimit'; mint: string; amount: string; destination: string }
  | { type: 'TokenRecurringDestinationLimit'; mint: string; recurringAmount: string; window: string; destination: string }

  // Program access
  | { type: 'Program'; programId: string }
  | { type: 'ProgramAll' }
  | { type: 'ProgramCurated' }

  // Staking
  | { type: 'StakeLimit'; amount: string }
  | { type: 'StakeRecurringLimit'; recurringAmount: string; window: string }
  | { type: 'StakeAll' }

  // Sub-accounts
  | { type: 'SubAccount' };
```

## Error Handling

<Tabs>
  <Tab title="API SDK">
    ```typescript theme={null}
    import { SwigApiClient, ApiError } from '@swig-wallet/api';

    const client = new SwigApiClient({
      apiKey: 'sk_your_api_key',
    });

    const { data, error } = await client.policies.get('invalid-policy-id');

    if (error) {
      // ApiError properties:
      // - message: Human-readable error message
      // - code: Error code string (e.g., 'NOT_FOUND', 'UNAUTHORIZED')
      // - status: HTTP status code
      // - details: Additional error context (if available)

      switch (error.code) {
        case 'NOT_FOUND':
          console.log('Policy does not exist');
          break;
        case 'UNAUTHORIZED':
          console.log('Invalid or expired API key');
          break;
        default:
          console.log(`Unexpected error: ${error.message}`);
      }
    }
    ```
  </Tab>

  <Tab title="Developer SDK">
    ```typescript theme={null}
    import { SwigClient, SwigError } from '@swig-wallet/developer';

    const client = new SwigClient({
      apiKey: 'sk_your_api_key',
      baseUrl: 'https://dashboard.onswig.com',
    });

    try {
      const policy = await client.getPolicy('invalid-policy-id');
    } catch (error) {
      if (error instanceof SwigError) {
        // SwigError properties:
        // - message: Human-readable error message
        // - code: Error code string (e.g., 'POLICY_NOT_FOUND')
        // - statusCode: HTTP status code
        // - response: Raw response data (if available)

        switch (error.code) {
          case 'POLICY_NOT_FOUND':
            console.log('Policy does not exist');
            break;
          case 'UNAUTHORIZED':
            console.log('Invalid or expired API key');
            break;
          default:
            console.log(`Unexpected error: ${error.message}`);
        }
      }
    }
    ```
  </Tab>
</Tabs>

### Common Errors

| Status | Code                             | Meaning                                    |
| ------ | -------------------------------- | ------------------------------------------ |
| 401    | `UNAUTHORIZED`                   | Invalid or missing API key                 |
| 403    | `FORBIDDEN`                      | API key doesn't have access to this policy |
| 404    | `NOT_FOUND` / `POLICY_NOT_FOUND` | Policy ID doesn't exist                    |
| 500    | `INTERNAL_ERROR`                 | Server error, try again later              |

## Retry Configuration

Both SDKs support automatic retries for transient failures:

<Tabs>
  <Tab title="API SDK">
    ```typescript theme={null}
    const client = new SwigApiClient({
      apiKey: 'sk_your_api_key',
      portalUrl: 'https://dashboard.onswig.com',
      retry: {
        maxRetries: 3,        // Number of retry attempts
        retryDelay: 1000,     // Initial delay in milliseconds
        backoffMultiplier: 2, // Exponential backoff multiplier
      },
    });
    ```
  </Tab>

  <Tab title="Developer SDK">
    ```typescript theme={null}
    const client = new SwigClient({
      apiKey: 'sk_your_api_key',
      baseUrl: 'https://dashboard.onswig.com',
      retryOptions: {
        maxRetries: 3,
        retryDelay: 1000,
        backoffMultiplier: 2,
      },
    });
    ```
  </Tab>
</Tabs>

With these settings, retries occur at: 1s, 2s, 4s (exponential backoff).

<Tip>
  Both SDKs only retry on 5xx server errors and network failures. Client errors (4xx) are not retried.
</Tip>

## Complete Example

<Tabs>
  <Tab title="API SDK">
    ```typescript theme={null}
    import { SwigApiClient } from '@swig-wallet/api';

    async function main() {
      const client = new SwigApiClient({
        apiKey: process.env.SWIG_API_KEY!,
        portalUrl: 'https://dashboard.onswig.com',
        retry: { maxRetries: 3, retryDelay: 1000 },
      });

      const policyId = 'your-policy-id';
      const { data: policy, error } = await client.policies.get(policyId);

      if (error) {
        console.error('Failed to fetch policy:', error.message);
        process.exit(1);
      }

      console.log('=== Policy Details ===');
      console.log(`ID: ${policy.id}`);
      console.log(`Name: ${policy.name}`);
      console.log(`Description: ${policy.description ?? 'None'}`);

      console.log('\n=== Authority ===');
      if (policy.authority) {
        console.log(`Type: ${policy.authority.type}`);
        console.log(`Public Key: ${policy.authority.publicKey}`);
      } else {
        console.log('No authority configured');
      }

      console.log('\n=== Actions ===');
      for (const action of policy.actions) {
        console.log(`- ${action.type}`);
      }
    }

    main();
    ```
  </Tab>

  <Tab title="Developer SDK">
    ```typescript theme={null}
    import { SwigClient, SwigError } from '@swig-wallet/developer';

    async function main() {
      const client = new SwigClient({
        apiKey: process.env.SWIG_API_KEY!,
        baseUrl: 'https://dashboard.onswig.com',
        retryOptions: { maxRetries: 3, retryDelay: 1000 },
      });

      try {
        const policy = await client.getPolicy('your-policy-id');

        console.log('=== Policy Details ===');
        console.log(`ID: ${policy.id}`);
        console.log(`Name: ${policy.name}`);

        console.log('\n=== Authority ===');
        if (policy.authority) {
          console.log(`Type: ${policy.authority.type}`);
          console.log(`Is Session: ${policy.authority.isSession()}`);
          console.log(`Is Ed25519: ${policy.authority.isEd25519()}`);
        } else {
          console.log('No authority configured');
        }

        console.log('\n=== Permissions ===');
        console.log(`Is Root: ${policy.actions.isRoot()}`);
        console.log(`Can Manage Authority: ${policy.actions.canManageAuthority()}`);

        const solLimit = policy.actions.solSpendLimit();
        console.log(`SOL Limit: ${solLimit ? `${solLimit} lamports` : 'None'}`);
      } catch (error) {
        if (error instanceof SwigError) {
          console.error('Failed to fetch policy:', error.message);
          process.exit(1);
        }
        throw error;
      }
    }

    main();
    ```
  </Tab>
</Tabs>

## Next Steps

Now that you can fetch policies, learn how to [create Swig wallets](./create-swig) using those policies.


# Developer Portal
Source: https://build.onswig.com/examples/dev-portal/index

"The best API is the one that gets out of your way" - A wise developer

The Swig Developer Portal is your central hub for managing API access, policies, and wallet creation. Whether you're building a dApp, integrating Swig wallets, or setting up transaction sponsorship, the portal provides the tools you need.

## What You Can Do

The Developer Portal enables you to:

* **Create and manage API keys** for authenticated access to Swig services
* **Define policies** that combine signers and permissions for wallet creation
* **Create Swig wallets** programmatically using your configured policies
* **Monitor usage** and manage your organization's resources

## Getting Started

Before using the Developer Portal features, you'll need:

1. A Swig account at [dashboard.onswig.com](https://dashboard.onswig.com)
2. An organization (created automatically on signup)

## Portal Sections

<CardGroup>
  <Card title="Organizations" icon="building" href="/examples/dev-portal/organizations">
    Manage your organization, team members, and billing
  </Card>

  <Card title="API Keys" icon="key" href="/examples/dev-portal/create-api-key">
    Generate API keys for programmatic access to Swig services
  </Card>

  <Card title="Policies & Wallets" icon="shield" href="/examples/dev-portal/create-policy">
    Define policies and create Swig wallets programmatically
  </Card>

  <Card title="Paymaster" icon="credit-card" href="/examples/dev-portal/paymaster-overview">
    Set up and manage transaction sponsorship
  </Card>

  <Card title="API Reference" icon="book" href="/examples/dev-portal/api-reference">
    Complete API documentation and endpoints
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/examples/dev-portal/error-codes">
    Error codes and debugging guides
  </Card>
</CardGroup>

## Next Steps

Start by reviewing your [organization settings](/examples/dev-portal/organizations) or [create an API key](/examples/dev-portal/create-api-key) to access the Swig API programmatically.


# Managing Members & Roles
Source: https://build.onswig.com/examples/dev-portal/manage-members

"Great teams build great wallets" - Swig Collaboration

This guide covers how to invite team members, manage roles, and handle permissions in your Swig organization.

## Member Roles

Swig uses role-based access control with four distinct roles:

| Role        | Access Level | Description                                                         |
| ----------- | ------------ | ------------------------------------------------------------------- |
| **Owner**   | Full         | Complete control including billing, members, and ownership transfer |
| **Admin**   | High         | Can manage members and most settings (except other owners)          |
| **Member**  | Standard     | Access to project resources (API keys, policies, paymasters)        |
| **Billing** | Limited      | View and manage billing only                                        |

### Role Hierarchy

```
Owner (100)
  └── Admin (75)
        └── Member (50)

Billing (25) - Special role, isolated permissions
```

### Permission Matrix

| Action              | Owner | Admin | Member | Billing |
| ------------------- | ----- | ----- | ------ | ------- |
| View dashboard      | ✓     | ✓     | ✓      | ✓       |
| Manage API keys     | ✓     | ✓     | ✓      | ✗       |
| Manage policies     | ✓     | ✓     | ✓      | ✗       |
| Manage paymasters   | ✓     | ✓     | ✓      | ✗       |
| Invite members      | ✓     | ✓     | ✗      | ✗       |
| Remove members      | ✓     | ✓     | ✗      | ✗       |
| Change roles        | ✓     | ✓\*   | ✗      | ✗       |
| Access billing      | ✓     | ✓     | ✗      | ✓       |
| Delete organization | ✓     | ✗     | ✗      | ✗       |
| Transfer ownership  | ✓     | ✗     | ✗      | ✗       |

\*Admins cannot change roles of owners

## Inviting Members

### Step 1: Navigate to Members

1. Log in to the [Developer Portal](https://dashboard.onswig.com)
2. Select your organization
3. Click **Members** in the sidebar

### Step 2: Send Invitation

1. Click **Invite Member**
2. Enter the member's **email address**
3. Select a **role**:
   * Owner (only owners can invite other owners)
   * Admin
   * Member
   * Billing
4. Click **Send Invitation**

### Step 3: Invitation Sent

The invitee receives an email with:

* Organization name
* Your name (as inviter)
* Invitation link
* Expiration date (7 days)

<Tip>
  Invitations expire after 7 days. You can resend them if they expire.
</Tip>

## Accepting Invitations

### Via Email Link

1. Click the invitation link in the email
2. Sign in or create a Swig account
3. Accept the invitation
4. You're now a member of the organization

### Via Dashboard

If you're already logged in:

1. Go to [dashboard.onswig.com](https://dashboard.onswig.com)
2. You'll see pending invitations in your dashboard
3. Click **Accept** to join the organization

## Managing Existing Members

### Viewing Members

The Members page shows:

* Member name and email
* Role (Owner, Admin, Member, Billing)
* Join date
* Available actions

### Changing Roles

1. Find the member in the list
2. Click the role dropdown or action menu
3. Select the new role
4. Confirm the change

**Restrictions:**

* Only owners can assign the Owner role
* Admins cannot change roles of other owners
* You cannot demote yourself if you're the last owner

### Removing Members

1. Find the member in the list
2. Click **Remove** or the delete icon
3. Confirm the removal

**Restrictions:**

* The last owner cannot be removed
* Owners and admins can remove members
* Members cannot remove other members

## Special Actions

### Promoting to Owner

Only owners can promote members to the Owner role:

1. Find the member in the list
2. Click **Promote to Owner** (or select Owner from role dropdown)
3. Confirm the promotion

### Transferring Ownership

Transfer the primary owner designation:

1. Go to organization settings
2. Click **Transfer Ownership**
3. Select the new owner (must be an existing member)
4. Confirm the transfer

<Warning>
  Transferring ownership changes the `ownerId` of the organization. The previous owner retains Owner role but is no longer the primary owner.
</Warning>

### Leaving an Organization

To remove yourself from an organization:

1. Go to organization settings
2. Click **Leave Organization**
3. Confirm your departure

**Restrictions:**

* The last owner cannot leave
* Transfer ownership first if you need to leave as the sole owner

## Seat Limits

Team seats are limited based on your subscription tier:

| Tier       | Seat Limit       |
| ---------- | ---------------- |
| FREE       | 1                |
| PRO        | Limited (varies) |
| ULTRA      | Limited (varies) |
| ENTERPRISE | Unlimited        |

### Reaching Seat Limit

When at your seat limit:

* The **Invite Member** button is disabled
* A message indicates you've reached the limit
* You can upgrade your subscription for more seats

### Adding More Seats

1. Go to **Billing** in the sidebar
2. Click **Upgrade** or **Add Seats**
3. Select additional seats or upgrade tier
4. Complete the payment

## Pending Invitations

### Viewing Invitations

Owners and admins can see all pending invitations:

* Navigate to the Members page
* View the **Pending Invitations** section
* See email, role, and expiration date

### Managing Invitations

**Resend Invitation:**

* Click **Resend** to send a new email
* This doesn't change the expiration date

**Cancel Invitation:**

* Click **Cancel** to revoke the invitation
* The link will no longer work

**Delete Invitation:**

* Click **Delete** to permanently remove
* Use for cleaning up old invitations

## Best Practices

### Role Assignment

* **Owners**: Key decision-makers, founders, CTOs
* **Admins**: Team leads, project managers
* **Members**: Developers, engineers
* **Billing**: Finance team, accountants

### Security

* Regularly audit member access
* Remove members who leave the team
* Use the minimum role necessary
* Enable 2FA for all owners and admins

### Organization Structure

For larger teams, consider:

* One owner per organization (clearer ownership)
* Multiple admins for redundancy
* Clear documentation of role responsibilities

## Troubleshooting

### Invitation Not Received

1. Check spam/junk folder
2. Verify the email address
3. Resend the invitation
4. Try a different email address

### Cannot Change Role

Possible causes:

* You're not an owner or admin
* You're trying to modify an owner (as admin)
* You're the last owner

### Cannot Remove Member

Possible causes:

* The member is the last owner
* You don't have sufficient permissions

## Next Steps

* [Set up subscriptions](./subscriptions-billing) for your team
* [Create API keys](./create-api-key) for team members
* [Define policies](./create-policy) for wallet access


# Managing Paymasters
Source: https://build.onswig.com/examples/dev-portal/manage-paymaster

"Keep your paymasters healthy, keep your users happy" - Swig Ops

This guide covers how to manage, configure, and monitor your paymasters in the Swig Developer Portal.

## Viewing Paymasters

### Paymaster List

1. Log in to the [Developer Portal](https://dashboard.onswig.com)
2. Select your organization
3. Click **Paymaster** in the sidebar

The list shows:

* **Label** - Display name
* **Address** - Solana public key
* **Balance** - Current SOL balance
* **Status** - Active or closed
* **Network** - Mainnet or devnet
* **Actions** - Edit, view, delete

### Paymaster Details

Click a paymaster to view:

* Full configuration
* Balance history
* Usage statistics
* Transaction history

## Editing Settings

### Accessing Edit

1. Find the paymaster in the list
2. Click **Edit** or the settings icon
3. Modify the settings
4. Click **Save**

### Editable Settings

#### Label

Update the display name:

* Descriptive and clear
* Maximum 64 characters
* Example: `production-mainnet-v2`

#### Usage API Threshold

Adjust API call limits:

* Increase for higher usage
* Decrease to reduce exposure
* Minimum: 1

#### SOL Usage Threshold

Modify monthly SOL spending limit:

* Set based on expected usage
* Consider adding buffer
* Minimum: 0.000000001 SOL

#### Single TX Limit

Change per-transaction limit:

* Balance security vs. functionality
* Higher for DeFi operations
* Lower for simple transfers

#### Allow Other Instructions

Toggle non-Swig instruction sponsorship:

* `false` - Only Swig instructions (recommended)
* `true` - Any instruction (use carefully)

## Monitoring Balance

### Current Balance

View the paymaster's SOL balance:

* Displayed in SOL
* Updates from blockchain
* Refresh to get latest

### Balance Alerts

For Enterprise accounts:

1. Set a low balance threshold
2. Configure alert recipients
3. Receive notifications when balance drops

### Funding

When balance is low:

1. Copy the paymaster address
2. Send SOL from any wallet
3. Balance updates after confirmation

## Usage Monitoring

### Current Period Usage

View usage for the current billing period:

* API calls made
* SOL spent
* USD value sponsored
* Transactions count

### Usage Limits

Track progress toward limits:

* Progress bars show percentage used
* Warnings at 80% and 90%
* Critical at 100%

### Usage Reset

Usage resets at the start of each billing period:

* Monthly reset
* Counters go back to zero
* Limits restored

## Limit Management

### Understanding Limits

| Limit Type          | Scope            | Reset   |
| ------------------- | ---------------- | ------- |
| Usage API Threshold | Per paymaster    | Monthly |
| SOL Usage Threshold | Per paymaster    | Monthly |
| Single TX Limit     | Per transaction  | N/A     |
| Subscription Limit  | Per organization | Monthly |

### Adjusting Limits

When to increase limits:

* Legitimate usage growth
* New product launch
* Seasonal traffic increase

When to decrease limits:

* Security concern
* Cost control
* Usage normalization

### Limit Hierarchy

Transactions are checked against:

1. Single TX limit (per paymaster)
2. SOL usage threshold (per paymaster)
3. Subscription limit (organization-wide)

## Closing a Paymaster

### When to Close

* No longer needed
* Consolidating paymasters
* Environment cleanup

### Close Process

1. Find the paymaster in the list
2. Click **Close** or the close icon
3. Enter a destination address for remaining funds
4. Confirm the closure

### What Happens

* Paymaster marked as deleted
* Remaining SOL transferred to destination
* Transaction history preserved
* Cannot be reactivated

<Warning>
  Closing a paymaster is permanent. Make sure to update any applications using it before closing.
</Warning>

## Deleting a Paymaster

### Permanent Deletion

After closing, you can permanently delete:

1. Find the closed paymaster
2. Click **Delete**
3. Confirm deletion

<Warning>
  Deletion is irreversible. Transaction history may be lost.
</Warning>

## Network Selection

### Switching Networks

View paymasters by network:

1. Click the **Network Toggle**
2. Select **Mainnet** or **Devnet**
3. View paymasters for that network

### Network-Specific Paymasters

Create separate paymasters for:

* **Devnet** - Testing and development
* **Mainnet** - Production applications

## Best Practices

### Regular Monitoring

* Check balances weekly (or daily for high-volume)
* Review usage trends
* Identify anomalies early

### Conservative Limits

Start with conservative limits:

* Easier to increase than decrease
* Limits exposure if issues occur
* Adjust based on data

### Documentation

Keep records of:

* Paymaster purpose
* Expected usage
* Configuration rationale

### Alerting

Set up alerts for:

* Low balance (Enterprise)
* High usage
* Failed transactions

## Troubleshooting

### Transaction Failures

If transactions fail:

1. Check paymaster balance
2. Verify limits aren't exceeded
3. Confirm paymaster is active
4. Check transaction details in history

### Balance Not Updating

If balance doesn't update:

1. Wait for blockchain confirmation
2. Refresh the page
3. Check if transfer succeeded on explorer

### Cannot Edit Paymaster

Possible causes:

* Paymaster is closed
* Insufficient permissions
* API error (try again)

## Enterprise Features

### Low Balance Alerts

Configure alerts:

1. Set threshold (in lamports)
2. Add recipient emails
3. Alerts sent with 24-hour cooldown

### Custom Limits

Enterprise accounts can request:

* Custom monthly limits
* Custom per-transaction limits
* Priority processing

### Dedicated Support

Enterprise accounts get:

* Dedicated support contact
* Faster response times
* Custom configuration help

## Next Steps

* [View transaction history](./transaction-history) for detailed analytics
* [Create more paymasters](./create-paymaster) for different use cases
* [Manage subscriptions](./subscriptions-billing) for higher limits


# Organizations Overview
Source: https://build.onswig.com/examples/dev-portal/organizations

"Together we build, together we Swig" - Swig Team

Organizations are the foundation of your Swig Developer Portal experience. They serve as containers for your projects, team members, API keys, policies, and paymasters.

## What is an Organization?

An organization in Swig represents a project or company that uses the Swig protocol. Each organization has:

* **Members** with different roles and permissions
* **A subscription** that determines available features
* **API keys** for programmatic access
* **Policies** defining wallet permissions
* **Paymasters** for transaction sponsorship

## Key Features

### Team Collaboration

Organizations support multiple members with role-based access control:

| Role        | Description                                                         |
| ----------- | ------------------------------------------------------------------- |
| **Owner**   | Full access to everything, including billing and ownership transfer |
| **Admin**   | Can manage members and most settings                                |
| **Member**  | Standard access to project resources                                |
| **Billing** | Access to billing and subscription management only                  |

### Subscription Tiers

Each organization has a subscription that determines available features:

| Feature          | FREE | PRO       | ULTRA     | ENTERPRISE |
| ---------------- | ---- | --------- | --------- | ---------- |
| API Keys         | 1    | Unlimited | Unlimited | Unlimited  |
| Paymaster Access | No   | Yes       | Yes       | Yes        |
| Paymaster Limit  | -    | \$10k/mo  | \$20k/mo  | Custom     |
| Team Seats       | 1    | Limited   | Limited   | Unlimited  |

### Automatic Setup

When you sign up for Swig:

1. An organization is automatically created for you
2. You're assigned as the **Owner**
3. A **FREE** subscription is activated
4. You can start creating API keys and policies immediately

## Organization Structure

```
Organization
├── Members (Owner, Admins, Members, Billing)
├── Subscription (FREE, PRO, ULTRA, ENTERPRISE)
├── API Keys
├── Policies
│   ├── Signers
│   └── Permissions
└── Paymasters
```

## Getting Started

<CardGroup>
  <Card title="Create Organization" icon="plus" href="./create-organization">
    Set up a new organization for your project
  </Card>

  <Card title="Manage Members" icon="users" href="./manage-members">
    Invite team members and manage roles
  </Card>

  <Card title="Subscriptions & Billing" icon="credit-card" href="./subscriptions-billing">
    Upgrade your plan and manage billing
  </Card>
</CardGroup>

## Best Practices

### Organization Naming

Choose a clear, descriptive name for your organization:

* Use your company or project name
* Keep it recognizable for team members
* Avoid special characters

### Role Assignment

Follow the principle of least privilege:

* Give **Owner** role only to key decision-makers
* Use **Admin** for team leads who need member management
* Assign **Member** role for developers
* Use **Billing** for finance team members who only need billing access

### Multiple Organizations

You can be a member of multiple organizations:

* Use separate organizations for different projects
* Keep production and development environments separate
* Maintain clear boundaries between client projects

## Next Steps

* [Create an organization](./create-organization) for your project
* [Invite team members](./manage-members) to collaborate
* [Choose a subscription](./subscriptions-billing) that fits your needs


# Paymaster Overview
Source: https://build.onswig.com/examples/dev-portal/paymaster-overview

"Sponsor transactions, delight users" - Swig Paymasters

Paymasters enable gasless transactions by sponsoring transaction fees on behalf of your users. This creates a seamless user experience where users don't need SOL to interact with your application.

## What is a Paymaster?

A paymaster is a Solana wallet managed by Swig that:

* **Holds SOL** for sponsoring transaction fees
* **Signs transactions** as the fee payer
* **Tracks usage** for billing and limits
* **Enforces limits** to prevent abuse

When a user submits a transaction through your application, the paymaster covers the transaction fee, allowing users to transact without holding SOL.

## How It Works

```
User creates transaction
        ↓
Your app sends to Swig Paymaster
        ↓
Paymaster signs as fee payer
        ↓
Transaction submitted to Solana
        ↓
User's action succeeds (gasless!)
```

## Subscription Requirements

Paymasters are available on **paid tiers only**:

| Tier       | Paymaster Access | Monthly Limit | Fee Rate |
| ---------- | ---------------- | ------------- | -------- |
| FREE       | No               | -             | -        |
| PRO        | Yes              | \$10,000      | 8%       |
| ULTRA      | Yes              | \$20,000      | 7%       |
| ENTERPRISE | Yes              | Custom        | 6%       |

<Warning>
  FREE tier accounts cannot create paymasters. Upgrade to PRO or higher to access paymaster features.
</Warning>

## Key Concepts

### Paymaster Limits

Each paymaster has configurable limits:

| Limit                   | Description                | Default |
| ----------------------- | -------------------------- | ------- |
| **Usage API Threshold** | Max API calls per month    | 1,000   |
| **SOL Usage Threshold** | Max SOL to spend per month | 10 SOL  |
| **Single TX Limit**     | Max SOL per transaction    | 0.1 SOL |

### Monthly Limits

Your subscription tier determines your monthly sponsorship limit:

* Measured in USD value
* Resets at the start of each billing period
* Overage billing applies if exceeded

### Paymaster Balance

Each paymaster needs SOL to sponsor transactions:

* Fund the paymaster after creation
* Monitor balance to prevent failed transactions
* Low balance alerts available for Enterprise

## Use Cases

### User Onboarding

Remove friction for new users:

* Users don't need to acquire SOL first
* Immediate access to your application
* Higher conversion rates

### In-App Transactions

Seamless in-app experiences:

* Token transfers
* NFT minting
* DeFi interactions
* Game actions

### Subscription Services

Automate recurring transactions:

* Payment processing
* Subscription renewals
* Scheduled operations

## Paymaster vs Direct SDK

| Feature        | Paymaster (Portal API) | Direct SDK          |
| -------------- | ---------------------- | ------------------- |
| Fee Payer      | Paymaster wallet       | User's wallet       |
| User needs SOL | No                     | Yes                 |
| Usage tracking | Automatic              | Manual              |
| Billing        | Included               | N/A                 |
| Setup          | Portal configuration   | Code configuration  |
| Best for       | Production apps        | Development/testing |

## Getting Started

<CardGroup>
  <Card title="Create a Paymaster" icon="plus" href="./create-paymaster">
    Set up your first paymaster
  </Card>

  <Card title="Manage Paymasters" icon="gear" href="./manage-paymaster">
    Configure settings and monitor usage
  </Card>

  <Card title="Transaction History" icon="clock" href="./transaction-history">
    View sponsored transactions and analytics
  </Card>
</CardGroup>

## Security

### Access Control

* Paymasters are scoped to your organization
* API keys authenticate requests
* Per-paymaster limits prevent abuse

### Allow Other Instructions

By default, paymasters only sponsor Swig-related instructions. You can enable `allowOtherIxs` to sponsor any instruction, but use caution:

<Warning>
  Enabling `allowOtherIxs` allows sponsoring any transaction type. This increases flexibility but also potential for abuse.
</Warning>

### Monitoring

* Track all sponsored transactions
* View real-time usage metrics
* Set up alerts for anomalies

## Best Practices

### Start with Limits

Begin with conservative limits:

* Low single transaction limit
* Moderate monthly threshold
* Increase as you understand usage patterns

### Monitor Usage

Regularly review:

* Transaction volume
* SOL spending
* Error rates

### Maintain Balance

Keep paymaster funded:

* Monitor balance regularly
* Set up low balance alerts (Enterprise)
* Automate top-ups if possible

### Separate Environments

Use different paymasters for:

* Development (devnet)
* Staging
* Production (mainnet)

## Next Steps

* [Create your first paymaster](./create-paymaster)
* [Learn about settings and limits](./manage-paymaster)
* [View transaction history](./transaction-history)


# Subscriptions & Billing
Source: https://build.onswig.com/examples/dev-portal/subscriptions-billing

"Invest in your infrastructure, scale your success" - Swig Finance

This guide covers subscription tiers, billing management, and usage tracking in the Swig Developer Portal.

## Subscription Tiers

Swig offers four subscription tiers to match your needs:

<Frame>
  <img alt="Swig Subscription Tiers" />
</Frame>

| Feature              | FREE    | PRO         | ULTRA       | ENTERPRISE     |
| -------------------- | ------- | ----------- | ----------- | -------------- |
| **Price**            | \$0/mo  | \$39/mo     | \$399/mo    | Custom         |
| **UserOps/month**    | 50,000  | 100,000     | 250,000     | 500,000+       |
| **Team Seats**       | 5       | 10          | 50          | Unlimited      |
| **Paymaster Access** | No      | Yes         | Yes         | Yes            |
| **Paymaster Limit**  | -       | \$10,000/mo | \$20,000/mo | Unlimited      |
| **Paymaster Fee**    | -       | 8%          | 7%          | 6%             |
| **SLA**              | 48 hour | 24 hour     | Dedicated   | 24/7           |
| **Overage Rate**     | -       | \$2.50/1k   | \$2.25/1k   | From \$2.00/1k |

## Managing Your Subscription

### Viewing Current Plan

1. Log in to the [Developer Portal](https://dashboard.onswig.com)
2. Go to **Billing** in the sidebar
3. View your current tier, usage, and limits

### Upgrading Your Plan

1. Go to **Billing** in the sidebar
2. Click **Upgrade**
3. Select your desired tier
4. Complete the Stripe checkout
5. Your new features are available immediately

### Downgrading Your Plan

1. Go to **Billing** in the sidebar
2. Click **Change Plan**
3. Select a lower tier
4. Confirm the change
5. The change takes effect at your next billing cycle

<Warning>
  When downgrading, ensure you're within the limits of your new tier. You may lose access to features or need to remove resources.
</Warning>

## Billing Portal

Access the Stripe billing portal for:

### Payment Methods

* Add or remove credit cards
* Set a default payment method
* Update billing information

### Invoices

* View invoice history
* Download invoices as PDF
* See payment status

### Subscription Details

* View current subscription
* See next billing date
* Cancel subscription

To access:

1. Go to **Billing** in the sidebar
2. Click **Manage Billing** or **Billing Portal**
3. You'll be redirected to Stripe

## Usage Tracking

### UserOps Usage

Track your UserOps consumption:

* **Monthly limit** - Maximum UserOps included in your tier
* **Current usage** - UserOps used this month
* **Remaining** - Available UserOps before overage

### Paymaster Usage

Track your paymaster spending:

* **Monthly limit** - Maximum USD value sponsored
* **Current usage** - USD value spent this month
* **Remaining** - Available budget

Usage metrics include:

* Total transactions sponsored
* Total SOL spent
* USD value (at transaction time)

### Viewing Usage

1. Go to **Billing** in the sidebar
2. View the **Usage** section
3. See current period metrics

## Overage Handling

### What Happens at Limit

When you reach your UserOps limit:

1. Additional UserOps are billed at your tier's overage rate
2. You're notified of the overage
3. An overage invoice is generated

### Overage Rates

| Tier       | Rate per 1,000 UserOps |
| ---------- | ---------------------- |
| PRO        | \$2.50                 |
| ULTRA      | \$2.25                 |
| ENTERPRISE | From \$2.00            |

### Limit Multiplier

After paying an overage invoice:

* Your limit is temporarily increased
* This helps prevent service interruption
* Resets at the start of the next billing period

## Usage Notifications

Swig sends notifications at key usage thresholds:

| Threshold | Notification                |
| --------- | --------------------------- |
| 50%       | Info - Halfway to limit     |
| 75%       | Warning - Approaching limit |
| 90%       | Alert - Near limit          |
| 99%       | Critical - Almost at limit  |
| 100%      | Limit reached               |

Configure notifications in your organization settings.

## Enterprise Features

### Custom Limits

Enterprise customers can configure:

* Custom UserOps limits
* Custom paymaster spending limits
* Custom pricing tiers

### Low Balance Alerts

For Enterprise accounts:

* Set a low balance threshold
* Receive alerts when paymaster balance is low
* Configure alert recipients

### Manual Management

Enterprise subscriptions can be:

* Manually managed by Swig
* Not synced from Stripe
* Customized per agreement

## Billing Cycle

### Monthly Billing

* Billed on the same day each month
* Usage tracked from period start to end
* Unused limits don't roll over

### Period Reset

At the start of each billing period:

* Usage counters reset to zero
* Limit multiplier resets (if applied)
* New billing cycle begins

## Cancellation

### Canceling a Subscription

1. Go to **Billing** in the sidebar
2. Click **Cancel Subscription**
3. Confirm the cancellation
4. Access continues until period end

### After Cancellation

* Downgraded to FREE tier
* Paymaster access removed
* Extra team members may lose access
* Data is retained

### Reactivating

To reactivate after cancellation:

1. Go to **Billing**
2. Select a paid tier
3. Complete payment

## FAQs

### When is my billing date?

Your billing date is the day you started your subscription. View it in the Billing section.

### Can I get a refund?

Contact support for refund requests. Refunds are handled on a case-by-case basis.

### What payment methods are accepted?

We accept all major credit cards through Stripe:

* Visa
* Mastercard
* American Express
* Discover

### Is there a free trial?

The FREE tier is always available with 50,000 UserOps/month. This is a great way to try out Swig before upgrading.

### How do I get Enterprise pricing?

Fill out the **Enterprise Contact Form** on the [Billing page](https://dashboard.onswig.com) in the Developer Portal to discuss custom Enterprise pricing.

## Next Steps

* [Create a paymaster](./create-paymaster) to sponsor transactions
* [Invite team members](./manage-members) to collaborate
* [Set up API keys](./create-api-key) for your applications


# Transaction History & Analytics
Source: https://build.onswig.com/examples/dev-portal/transaction-history

"Data drives decisions, transactions tell stories" - Swig Analytics

This guide covers how to view, filter, and analyze sponsored transactions in the Swig Developer Portal.

## Viewing Transaction History

### Accessing History

1. Log in to the [Developer Portal](https://dashboard.onswig.com)
2. Select your organization
3. Click **Paymaster** in the sidebar
4. Select a paymaster to view its transactions

### Transaction List

The transaction history shows:

* **Signature** - Solana transaction signature
* **Date/Time** - When the transaction occurred
* **Status** - Success, failed, or pending
* **Fee** - SOL spent on fees
* **Slot** - Blockchain slot number
* **Network** - Mainnet or devnet

## Transaction Details

Click a transaction to view:

### Basic Information

* Full transaction signature
* Timestamp (with timezone)
* Block/slot number
* Confirmation status

### Fee Information

* Fee in SOL
* Fee in lamports
* USD value at transaction time

### Links

* View on Solana Explorer
* View on Solscan
* Copy signature

## Filtering Transactions

### By Date Range

Select a time period:

* Last 24 hours
* Last 7 days
* Last 30 days
* Custom range

### By Status

Filter by transaction status:

* **All** - Show all transactions
* **Success** - Confirmed transactions
* **Failed** - Failed transactions
* **Pending** - Awaiting confirmation

### By Network

Toggle between networks:

* **Mainnet** - Production transactions
* **Devnet** - Test transactions

## Analytics Dashboard

### Overview Metrics

View aggregate statistics:

* **Total Transactions** - Count of sponsored transactions
* **Total SOL Spent** - Sum of fees paid
* **Total USD Value** - Dollar value sponsored
* **Average Fee** - Mean fee per transaction

### Time Series Charts

Visualize trends over time:

#### SOL Spent

* Daily/weekly/monthly SOL spending
* Identify usage patterns
* Spot anomalies

#### Transaction Volume

* Number of transactions over time
* Peak usage periods
* Growth trends

#### USD Value

* Dollar value of sponsored transactions
* Cost tracking
* Budget planning

### Chart Time Ranges

Select analysis period:

* **1 Hour** - Recent activity
* **1 Week** - Short-term trends
* **1 Month** - Monthly patterns

## Usage Metrics

### Current Period

View usage for the current billing period:

| Metric            | Description             |
| ----------------- | ----------------------- |
| API Calls         | Number of API requests  |
| SOL Spent         | Total SOL used for fees |
| USD Value         | Dollar value sponsored  |
| Transaction Count | Number of transactions  |

### Limit Progress

Visual indicators show:

* **Green** - Under 50% of limit
* **Yellow** - 50-80% of limit
* **Orange** - 80-90% of limit
* **Red** - Over 90% of limit

### Historical Usage

View past billing periods:

* Monthly aggregates
* Trend analysis
* Cost history

## Network Comparison

### Switching Networks

Toggle to compare activity:

* Devnet usage (development)
* Mainnet usage (production)

### Separate Tracking

Each network tracked independently:

* Separate transaction lists
* Separate usage counters
* Separate analytics

## Exporting Data

### Transaction Export

Export transaction data:

1. Apply desired filters
2. Click **Export**
3. Choose format (CSV, JSON)
4. Download file

### Export Fields

Exported data includes:

* Signature
* Timestamp
* Status
* Fee (SOL)
* Fee (lamports)
* Slot
* Network

## Real-Time Updates

### Live Status

Transaction status updates in real-time:

* Pending → Success
* Pending → Failed
* Balance updates

### Refresh

Click refresh to get latest data:

* Transaction list
* Usage metrics
* Balance

## Troubleshooting Transactions

### Failed Transactions

When a transaction fails:

1. Click the transaction
2. View the error message
3. Check the signature on Solana Explorer
4. Common causes:
   * Insufficient paymaster balance
   * Limit exceeded
   * Network congestion
   * Invalid transaction

### Missing Transactions

If a transaction doesn't appear:

1. Wait for blockchain confirmation
2. Refresh the page
3. Check the correct network (mainnet/devnet)
4. Verify the transaction was sent to this paymaster

### Duplicate Transactions

If you see duplicates:

1. Check transaction signatures (should be different)
2. Could be legitimate retries
3. Contact support if unexpected

## Analytics Best Practices

### Regular Review

* Daily: Check for anomalies
* Weekly: Review usage trends
* Monthly: Analyze cost and volume

### Alerting

Set up alerts for:

* Unusual transaction volume
* High failure rates
* Budget thresholds

### Budgeting

Use historical data to:

* Forecast future costs
* Plan capacity
* Set appropriate limits

## Integration with Billing

### Cost Attribution

Transaction history links to billing:

* Each transaction counted toward limits
* USD value affects subscription usage
* Overage triggers tracked

### Invoice Details

View transactions related to invoices:

* Which transactions incurred costs
* Breakdown by period
* Cost per paymaster

## API Access

### Programmatic Access

Query transaction history via API:

```typescript theme={null}
import { SwigApiClient } from '@swig-wallet/api';

const client = new SwigApiClient({
  apiKey: 'sk_your_api_key',
  portalUrl: 'https://dashboard.onswig.com',
});

// Transaction history is primarily accessed via the Dashboard
// For real-time monitoring, use webhook integrations (Enterprise)
```

### Webhook Integration (Enterprise)

Enterprise accounts can configure:

* Transaction webhooks
* Real-time notifications
* Custom integrations

## Next Steps

* [Manage paymaster settings](./manage-paymaster) to adjust limits
* [Create additional paymasters](./create-paymaster) for different use cases
* [Review billing](./subscriptions-billing) based on usage data


# Using Ethereum Keys with Swig
Source: https://build.onswig.com/examples/ethereum_keys

"Just use swig" - Vitalik Buterin (probably one day)

Swig supports using Ethereum-style secp256k1 keys for authorization, enabling you to use your Ethereum wallet to control assets on Solana. This guide explains how to integrate Ethereum wallets with Swig and showcases different implementation approaches.

## Current Implementation

Currently, Swig uses the compressed public key format for authentication (not the Ethereum address). A future update will introduce an `EvmAddress` authority type that uses the hashed form of the public key (the standard Ethereum address).

## Integration Examples

### Viem Integration (Recommended)

The recommended approach for Ethereum wallet integration uses the Viem library. Here's a complete example showing different signing methods:

<Tabs>
  <Tab title="Classic (SVM)">
    ```typescript theme={null}
    import { Wallet } from '@ethereumjs/wallet';
    import {
      Keypair,
      LAMPORTS_PER_SOL,
      PublicKey,
      SystemProgram,
      Transaction,
      TransactionInstruction,
    } from '@solana/web3.js';
    import {
      Actions,
      createSecp256k1AuthorityInfo,
      findSwigPda,
      getCreateSwigInstruction,
      getEvmPersonalSignPrefix,
      getSignInstructions,
      getSwigWalletAddress,
      Swig,
      SWIG_PROGRAM_ADDRESS,
      type SigningFn,
    } from '@swig-wallet/classic';
    import { hexToBytes, keccak256 } from 'viem';
    import { privateKeyToAccount } from 'viem/accounts';

    // Create an Ethereum wallet account
    const userWallet = Wallet.generate();
    const privateKeyAccount = privateKeyToAccount(userWallet.getPrivateKeyString());

    const transactionPayer = Keypair.generate();
    const dappTreasury = Keypair.generate().publicKey;
    const id = Uint8Array.from(Array(32).fill(0));
    const swigAccountAddress = findSwigPda(id);
    const rootActions = Actions.set().all().get();

    // Create Swig with secp256k1 authority
    const createSwigInstruction = await getCreateSwigInstruction({
      authorityInfo: createSecp256k1AuthorityInfo(privateKeyAccount.publicKey),
      id,
      payer: transactionPayer.publicKey,
      actions: rootActions,
    });

    // Fetch Swig and get wallet address
    let swig = fetchSwig(svm, swigAccountAddress);
    const swigWalletAddress = await getSwigWalletAddress(swig);
    let rootRole = swig.findRolesBySecp256k1SignerAddress(
      privateKeyAccount.address,
    )[0];

    // Different signing methods available:

    // 1. Direct keccak256 hash signing (raw message bytes)
    const viemSign: SigningFn = async (message: Uint8Array) => {
      const sig = await privateKeyAccount.sign({ hash: keccak256(message) });
      return { signature: hexToBytes(sig) };
    };

    // 2. Manual Ethereum personal sign prefix
    const viemSignWithPrefix: SigningFn = async (message: Uint8Array) => {
      const prefix = getEvmPersonalSignPrefix(message.length);
      const prefixedMessage = new Uint8Array(prefix.length + message.length);

      prefixedMessage.set(prefix);
      prefixedMessage.set(message, prefix.length);

      const sig = await privateKeyAccount.sign({ 
        hash: keccak256(prefixedMessage) 
      });

      return { signature: hexToBytes(sig), prefix };
    };

    // 3. Viem signMessage method (automatically adds Ethereum personal sign prefix)
    const viemSignMessage: SigningFn = async (message: Uint8Array) => {
      const sig = await privateKeyAccount.signMessage({ 
        message: { raw: message } 
      });
      
      return {
        signature: hexToBytes(sig),
        prefix: getEvmPersonalSignPrefix(message.length),
      };
    };

    // Create and sign a transfer transaction (use swigWalletAddress)
    const transfer = SystemProgram.transfer({
      fromPubkey: swigWalletAddress,
      toPubkey: dappTreasury,
      lamports: 0.1 * LAMPORTS_PER_SOL,
    });

    const signTransfer = await getSignInstructions(
      swig,
      rootRole.id,
      [transfer],
      false,
      {
        currentSlot: svm.getClock().slot,
        signingFn: viemSign, // or viemSignWithPrefix, or viemSignMessage
        payer: transactionPayer.publicKey,
      },
    );
    ```
  </Tab>

  <Tab title="Kit (Local)">
    ```typescript theme={null}
    import {
      createSolanaRpc,
      createSolanaRpcSubscriptions,
      generateKeyPairSigner,
      sendAndConfirmTransactionFactory,
      getSignatureFromTransaction,
      createTransactionMessage,
      setTransactionMessageFeePayerSigner,
      setTransactionMessageLifetimeUsingBlockhash,
      appendTransactionMessageInstructions,
      signTransactionMessageWithSigners,
      lamports,
      pipe,
      AccountRole,
      type IInstructionWithData,
      type KeyPairSigner,
      type ReadonlyUint8Array,
    } from '@solana/kit';

    import {
      Actions,
      createSecp256k1AuthorityInfo,
      findSwigPda,
      fetchSwig,
      getCreateSwigInstruction,
      getEvmPersonalSignPrefix,
      getSignInstructions,
      getSwigWalletAddress,
      type SigningFn,
    } from '@swig-wallet/kit';

    import {
      getTransferSolInstructionDataEncoder,
      SYSTEM_PROGRAM_ADDRESS,
    } from '@solana-program/system';

    import { Wallet } from '@ethereumjs/wallet';
    import { privateKeyToAccount } from 'viem/accounts';
    import { keccak256, hexToBytes } from 'viem';

    // Set up Solana localnet RPC
    const rpc = createSolanaRpc('http://localhost:8899');
    const rpcSubscriptions = createSolanaRpcSubscriptions('ws://localhost:8900');
    const connection = { rpc, rpcSubscriptions };

    // Generate EVM wallet
    const userWallet = Wallet.generate();
    const evmAccount = privateKeyToAccount(userWallet.getPrivateKeyString());

    // Generate localnet payers
    const payer = await generateKeyPairSigner();
    const dappTreasury = await generateKeyPairSigner();

    // Swig ID and address
    const swigId = Uint8Array.from(Array(32).fill(1));
    const swigAccountAddress = await findSwigPda(swigId);

    // Create Swig with secp256k1 authority
    const rootActions = Actions.set().all().get();
    const createSwigIx = await getCreateSwigInstruction({
      authorityInfo: createSecp256k1AuthorityInfo(evmAccount.publicKey),
      id: swigId,
      payer: payer.address,
      actions: rootActions,
    });

    // Fetch Swig account and get wallet address
    let swig = await fetchSwig(rpc, swigAccountAddress);
    const swigWalletAddress = await getSwigWalletAddress(swig);
    let rootRole = swig.findRolesBySecp256k1SignerAddress(evmAccount.address)[0];

    // Different signing methods available:

    // 1. Direct keccak256 hash signing (raw message bytes)
    const viemSign: SigningFn = async (message) => {
      const sig = await evmAccount.sign({ hash: keccak256(message) });
      return { signature: hexToBytes(sig) };
    };

    // 2. Manual Ethereum personal sign prefix
    const viemSignWithPrefix: SigningFn = async (message) => {
      const prefix = getEvmPersonalSignPrefix(message.length);
      const prefixedMessage = new Uint8Array(prefix.length + message.length);
      prefixedMessage.set(prefix);
      prefixedMessage.set(message, prefix.length);
      const sig = await evmAccount.sign({ hash: keccak256(prefixedMessage) });
      return { signature: hexToBytes(sig), prefix };
    };

    // 3. Viem signMessage method (automatically adds Ethereum personal sign prefix)
    const viemSignMessage: SigningFn = async (message) => {
      const sig = await evmAccount.signMessage({ message: { raw: message } });
      return {
        signature: hexToBytes(sig),
        prefix: getEvmPersonalSignPrefix(message.length),
      };
    };

    // Prepare transfer instruction (0.1 SOL, use swigWalletAddress)
    const transferIx = {
      programAddress: SYSTEM_PROGRAM_ADDRESS,
      accounts: [
        { address: swigWalletAddress, role: AccountRole.WRITABLE_SIGNER },
        { address: dappTreasury.address, role: AccountRole.WRITABLE },
      ],
      data: new Uint8Array(
        getTransferSolInstructionDataEncoder().encode({
          amount: lamports(100_000_000n), // 0.1 SOL
        }),
      ),
    };

    // Sign and send transfer
    const currentSlot = await rpc.getSlot().send();
    const signedIxs = await getSignInstructions(swig, rootRole.id, [transferIx], false, {
      payer: payer.address,
      currentSlot,
      signingFn: viemSign, // or viemSignWithPrefix, or viemSignMessage
    });
    ```
  </Tab>
</Tabs>

### Session-Based Authorization

For enhanced security and better UX, you can use session-based authorization with secp256k1 keys:

<Tabs>
  <Tab title="Classic">
    ```typescript theme={null}
    import {
      createSecp256k1SessionAuthorityInfo,
      getCreateSessionInstruction,
      getCreateSwigInstruction,
    } from '@swig-wallet/classic';

    // Create a session-based Swig
    const createSwigInstruction = await getCreateSwigInstruction({
      authorityInfo: createSecp256k1SessionAuthorityInfo(
        privateKeyAccount.publicKey,
        100n, // session duration in slots
      ),
      id,
      payer: transactionPayer.publicKey,
      actions: rootActions,
    });

    // Create a new session
    const newSessionInstruction = await getCreateSessionInstruction(
      swig,
      rootRole.id,
      dappSessionKeypair.publicKey,
      50n, // session duration
      {
        currentSlot: svm.getClock().slot,
        signingFn: viemSign,
        payer: transactionPayer.publicKey,
      }
    );
    ```
  </Tab>

  <Tab title="Kit">
    ```typescript theme={null}
    import {
      createSecp256k1SessionAuthorityInfo,
      getCreateSessionInstruction,
      getCreateSwigInstruction,
    } from '@swig-wallet/kit';

    // Create a session-based Swig
    const createSwigInstruction = await getCreateSwigInstruction({
      authorityInfo: createSecp256k1SessionAuthorityInfo(
        evmAccount.publicKey,
        100n, // session duration in slots
      ),
      id: swigId,
      payer: payer.address,
      actions: rootActions,
    });

    // Create a new session
    const newSessionInstruction = await getCreateSessionInstruction(
      swig,
      rootRole.id,
      dappSessionKeypair.address,
      50n, // session duration
      {
        currentSlot: await rpc.getSlot().send(),
        signingFn: viemSign,
        payer: payer.address,
      }
    );
    ```
  </Tab>
</Tabs>

## Best Practices

1. **Wallet Integration**
   * Use the Viem examples as your primary reference for Ethereum wallet integration
   * Choose the appropriate signing method based on your wallet implementation:
     * **Direct keccak256**: Signs raw message bytes directly
     * **Manual prefix**: Adds `\x19Ethereum Signed Message:\n{length}` prefix manually
     * **Viem signMessage**: Automatically adds Ethereum personal sign prefix
   * Test all three signing methods for maximum wallet compatibility

2. **API Differences**
   * **Classic**: Uses `getCreateSwigInstruction()`, `getSignInstructions()`, and `fetchSwig()` from SVM context
   * **Kit**: Uses similar functions but with Solana Kit's RPC and address types
   * Both support the same signing methods and authority types

3. **Security Considerations**
   * Use session-based authorities for dApp integrations to limit exposure
   * Keep session durations appropriate for your use case
   * Remember that while using Ethereum keys, you still need a Solana account for transaction fees

4. **Implementation Tips**
   * Use the provided helper functions like `createSecp256k1AuthorityInfo`
   * Implement proper error handling for signing operations
   * Use `findRolesBySecp256k1SignerAddress()` to locate roles by Ethereum address

## Future Developments

The upcoming `EvmAddress` authority type will allow using the standard Ethereum address format (the hashed form of the public key) instead of the current compressed public key format. This will make integration even more straightforward and familiar to Ethereum developers.

## Additional Resources

For complete working examples, check out these files in the [swig-ts](https://github.com/anagrambuild/swig-ts) repository:

**Classic Examples:**

* [`examples/basic/classic/using-viem.ts`](https://github.com/anagrambuild/swig-ts/blob/main/examples/basic/classic/using-viem.ts) - Viem integration
* [`examples/basic/classic/transfer-secp-session.ts`](https://github.com/anagrambuild/swig-ts/blob/main/examples/basic/classic/transfer-secp-session.ts) - Session-based authorization
* [`examples/basic/classic/transfer-secp.ts`](https://github.com/anagrambuild/swig-ts/blob/main/examples/basic/classic/transfer-secp.ts) - Basic secp256k1 usage

**Kit Examples:**

* [`examples/basic/kit/using-viem.ts`](https://github.com/anagrambuild/swig-ts/blob/main/examples/basic/kit/using-viem.ts) - Viem integration with Kit
* [`examples/basic/kit/transfer-secp.ts`](https://github.com/anagrambuild/swig-ts/blob/main/examples/basic/kit/transfer-secp.ts) - Secp256k1 example with Kit

You can also explore the full examples directory in the [swig-ts repository](https://github.com/anagrambuild/swig-ts/tree/main/examples) for more implementation patterns and use cases.


# Swig How-to's
Source: https://build.onswig.com/examples/index

"All I was asking for was a simple example" - Elon Musk on Swig(probably)

# SWIG Examples

SWIG provides a variety of examples to help developers understand and implement SWIG in different scenarios. Whether you're building a new dApp from scratch or integrating SWIG into an existing application, we have examples to guide you through the process.

## Example Categories

Our examples cover various use cases including:

* In-app wallet integration
* Legacy dApp integration
* SWIG-native dApp development
* CLI applications
* Subscription-based applications (like SwigFlix)
* Wallet Standard integration

## Finding More Examples

We maintain an ever-growing collection of examples in our [awesome-swig repository](https://github.com/anagrambuild/awesome-swig). This community-driven resource includes:

* Complete application examples
* SDK usage demonstrations (both Rust and TypeScript)
* Integration patterns
* CLI tools and utilities

The awesome-swig repository is regularly updated with new examples and best practices from the SWIG community. We encourage developers to explore these examples and contribute their own implementations to help others learn and build with SWIG.

Remember that these examples are meant to serve as starting points and can be adapted to fit your specific needs.


# Adding Multiple Authorities Efficiently
Source: https://build.onswig.com/examples/multi_authority

"Why make many transaction when one transaction do trick?" - Kevin Malone, Swig Enthusiast

This guide explains how to efficiently add multiple authorities to a Swig account in batch operations. This is particularly useful when you need to set up complex permission structures or onboard multiple users at once, saving on transaction fees and improving atomicity.

You can find complete working examples in the Swig repository:

* [Classic Example](https://github.com/anagrambuild/swig-ts/blob/main/examples/basic/classic/multi-add-authorities.ts)

<Tip>
  This example uses LiteSVM for testing and demonstrates advanced authority
  management patterns.
</Tip>

## Why Batch Operations?

When setting up a Swig with multiple authorities, you have two options:

1. **Add authorities one at a time** - Simple but requires multiple transactions
2. **Batch add authorities** - More efficient, atomic, and cost-effective

## Two Approaches to Batch Adding

Swig provides two methods for batch adding authorities:

1. **During Creation**: Add multiple authorities when creating the Swig using `getCreateSwigInstructionBuilder`
2. **After Creation**: Add multiple authorities to an existing Swig using `getAddMultipleAuthoritiesInstructionBuilder`

Let's explore both approaches.

***

## Approach 1: Adding Authorities During Swig Creation

When creating a Swig, you can chain `.addAuthority()` calls to add multiple authorities in the creation transaction. This is ideal for initial setup.

### Key Differences from Basic Creation

Instead of `getCreateSwigInstruction`, use **`getCreateSwigInstructionBuilder`** which returns a builder that allows chaining.

```typescript theme={null}
import {
	Keypair,
	LAMPORTS_PER_SOL,
	Transaction,
	sendAndConfirmTransaction,
} from "@solana/web3.js";
import {
	Actions,
	createEd25519AuthorityInfo,
	findSwigPda,
	getCreateSwigInstructionBuilder,
} from "@swig-wallet/classic";

// Setup
const connection = new Connection("http://localhost:8899", "confirmed");
const rootUser = Keypair.generate();
const spendingAuthority = Keypair.generate();
const tokenAuthority = Keypair.generate();
const tokenMint = Keypair.generate().publicKey;

// Airdrop to root user
await connection.requestAirdrop(rootUser.publicKey, 100 * LAMPORTS_PER_SOL);

// Find Swig PDA
const id = new Uint8Array(32);
crypto.getRandomValues(id);
const swigAddress = findSwigPda(id);

// Create Swig with multiple authorities in one transaction
const createBuilder = await getCreateSwigInstructionBuilder({
	payer: rootUser.publicKey,
	swigAddress,
	id,
	actions: Actions.set().manageAuthority().get(), // Root can manage authorities too
	authorityInfo: createEd25519AuthorityInfo(rootUser.publicKey),
});

// Chain multiple authority additions
const instructions = await createBuilder
	.addAuthority(
		createEd25519AuthorityInfo(spendingAuthority.publicKey),
		Actions.set()
			.solLimit({ amount: BigInt(0.5 * LAMPORTS_PER_SOL) })
			.get()
	)
	.addAuthority(
		createEd25519AuthorityInfo(tokenAuthority.publicKey),
		Actions.set()
			.tokenLimit({ mint: tokenMint, amount: BigInt(1000000) })
			.get()
	)
	.getInstructions();

// Send transaction
const transaction = new Transaction().add(...instructions);
const signature = await sendAndConfirmTransaction(connection, transaction, [
	rootUser,
]);

console.log("✓ Swig created with 3 authorities");
console.log("Swig address:", swigAddress.toBase58());
```

### Key Points

* Use **`getCreateSwigInstructionBuilder`** instead of `getCreateSwigInstruction`
* Chain `.addAuthority()` calls for each additional authority
* Call `.getInstructions()` at the end to get all instructions
* All authorities are added in a **single atomic transaction**

***

## Approach 2: Adding Multiple Authorities to Existing Swig

Sometimes you need to add multiple authorities to an **existing** Swig. For this, use `getAddMultipleAuthoritiesInstructionBuilder`.

This is particularly useful for:

* **Team onboarding** - Adding multiple team members at once
* **Permission upgrades** - Granting multiple new authorities simultaneously
* **Dynamic authority management** - Responding to application events

```typescript theme={null}
import {
  Keypair,
  LAMPORTS_PER_SOL,
  Transaction,
  sendAndConfirmTransaction,
} from '@solana/web3.js';
import {
  Actions,
  createEd25519AuthorityInfo,
  fetchSwig,
  findSwigPda,
  getAddMultipleAuthoritiesInstructionBuilder,
  getCreateSwigInstruction,
} from '@swig-wallet/classic';

// Setup
const connection = new Connection('http://localhost:8899', 'confirmed');
const rootUser = Keypair.generate();

// Airdrop to root user
const airdrop = await connection.requestAirdrop(rootUser.publicKey, 100 * LAMPORTS_PER_SOL);
await connection.confirmTransaction(airdrop);

// Create a basic Swig first
const id = new Uint8Array(32);
crypto.getRandomValues(id);
const swigAddress = findSwigPda(id);

const createSwigIx = await getCreateSwigInstruction({
  payer: rootUser.publicKey,
  id,
  actions: Actions.set().all().get(), // Root has all permissions
  authorityInfo: createEd25519AuthorityInfo(rootUser.publicKey),
});

const createTx = new Transaction().add(createSwigIx);
await sendAndConfirmTransaction(connection, createTx, [rootUser]);

console.log('✓ Basic Swig created at:', swigAddress.toBase58());

// Wait for account to be created
await new Promise((resolve) => setTimeout(resolve, 2000));

// Now add multiple authorities to the existing Swig
const swig = await fetchSwig(connection, swigAddress);
const rootRole = swig.findRolesByEd25519SignerPk(rootUser.publicKey)[0];

// Generate new authorities
const authority1 = Keypair.generate();
const authority2 = Keypair.generate();
const authority3 = Keypair.generate();

console.log('Adding 3 new authorities:');
console.log(' Authority 1:', authority1.publicKey.toBase58());
console.log(' Authority 2:', authority2.publicKey.toBase58());
console.log(' Authority 3:', authority3.publicKey.toBase58());

// Build instruction to add multiple authorities
const addBuilder = await getAddMultipleAuthoritiesInstructionBuilder(
  swig,
  rootRole.id,
  {
    payer: rootUser.publicKey,
  },
);

// Chain authority additions with different permissions
const instructions = await addBuilder
  .addAuthority(
    createEd25519AuthorityInfo(authority1.publicKey),
    Actions.set().solLimit({ amount: BigInt(0.1 _ LAMPORTS_PER_SOL) }).get(),
  )
  .addAuthority(
    createEd25519AuthorityInfo(authority2.publicKey),
    Actions.set().solLimit({ amount: BigInt(0.2 _ LAMPORTS_PER_SOL) }).get(),
  )
  .addAuthority(
    createEd25519AuthorityInfo(authority3.publicKey),
    Actions.set().solLimit({ amount: BigInt(0.3 * LAMPORTS_PER_SOL) }).get(),
  )
  .getInstructions();

const addTx = new Transaction().add(...instructions);
const signature = await sendAndConfirmTransaction(connection, addTx, [rootUser]);

console.log('✓ Added 3 authorities in one transaction');
console.log('Transaction signature:', signature);

// Verify the additions
await swig.refetch();
console.log('Swig now has', swig.roles.length, 'total authorities');

```

### Key Points for `getAddMultipleAuthoritiesInstructionBuilder`

1. **Fetch fresh Swig data** - Always fetch the latest Swig state before adding authorities
2. **Need proper permissions** - The signing role must have `all` or `manageAuthority` permission
3. **Chain additions** - Call `.addAuthority()` for each authority you want to add
4. **All or nothing** - The operation is atomic - all authorities are added or none

***

## Advanced: Multi-Curve Authorities

Swig supports multiple cryptographic curves. You can mix Ed25519, Secp256k1 (Ethereum), and Secp256r1 (Passkeys/WebAuthn) authorities in a single Swig!

```typescript theme={null}
import { Wallet } from "@ethereumjs/wallet";
import { p256 } from "@noble/curves/nist";
import { Keypair, LAMPORTS_PER_SOL } from "@solana/web3.js";
import {
	Actions,
	createEd25519AuthorityInfo,
	createSecp256k1AuthorityInfo,
	createSecp256r1AuthorityInfo,
	findSwigPda,
	getCreateSwigInstructionBuilder,
	getSigningFnForSecp256r1PrivateKey,
} from "@swig-wallet/classic";

// Setup
const connection = new Connection("http://localhost:8899", "confirmed");
const payer = Keypair.generate();

// Airdrop to root user
const airdrop = await connection.requestAirdrop(
	payer.publicKey,
	100 * LAMPORTS_PER_SOL
);
await connection.confirmTransaction(airdrop);

// Generate different curve types
const ed25519Authority = Keypair.generate();
const secp256k1Wallet = Wallet.generate();
const secp256r1PrivateKey = p256.keygen();
const secp256r1PublicKey = p256.getPublicKey(secp256r1PrivateKey);

// Create Swig with secp256r1 root
const id = new Uint8Array(32);
crypto.getRandomValues(id);
const swigAddress = findSwigPda(id);

const createBuilder = await getCreateSwigInstructionBuilder({
	options: {
		signingFn: getSigningFnForSecp256r1PrivateKey(secp256r1PrivateKey),
		currentSlot: await connection.getSlot(),
	},
	swigAddress,
	authorityInfo: createSecp256r1AuthorityInfo(secp256r1PublicKey),
	id,
	payer: payer.publicKey,
	actions: Actions.set().all().get(),
});

// Add authorities with different curves
const instructions = await createBuilder
	.addAuthority(
		createEd25519AuthorityInfo(ed25519Authority.publicKey),
		Actions.set().manageAuthority().get()
	)
	.addAuthority(
		createSecp256k1AuthorityInfo(secp256k1Wallet.getPublicKey()),
		Actions.set().all().get()
	)
	.getInstructions();

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

***

## When to Use Each Approach

| Scenario                                      | Recommended Method                                                     | Why                              |
| --------------------------------------------- | ---------------------------------------------------------------------- | -------------------------------- |
| **Initial Swig setup with known authorities** | Creation-time batching (`getCreateSwigInstructionBuilder`)             | Single transaction, atomic setup |
| **Adding team members to existing Swig**      | Post-creation batching (`getAddMultipleAuthoritiesInstructionBuilder`) | Efficient for existing Swigs     |
| **Adding authorities dynamically over time**  | Individual additions (`getAddAuthorityInstructions`)                   | More flexible, simpler API       |
| **Migrating from another system**             | Post-creation batching                                                 | Onboard multiple users at once   |

## Summary

* **Two batching methods** - Use builders for creation-time or post-creation batching
* **Atomic operations** - All authorities are added together or none at all
* **Multi-curve support** - Mix Ed25519, Secp256k1, and Secp256r1 authorities

## Related Examples

* [Transfer Example](./transfer) - Basic Swig usage with single authorities
* [Sessions Example](./sessions) - Temporary authorities with time limits
* [Sub Accounts Example](./sub_accounts) - Delegated account management

## Additional Resources

* [Complete multi-authority example](https://github.com/anagrambuild/swig-ts/blob/main/examples/basic/classic/multi-add-authorities.ts)


# Passkey Integration
Source: https://build.onswig.com/examples/passkeys

Integrate WebAuthn passkeys with Swig Wallet for secure, passwordless authentication on Solana

# Passkey Integration with Swig Wallet

This documentation covers how to integrate WebAuthn passkeys with Swig Wallet for secure, passwordless authentication on Solana.

## Reference Implementations

This guide references two key examples from the Swig TypeScript SDK:

* **[secp256r1 Transfer Example](https://github.com/anagrambuild/swig-ts/blob/main/examples/basic/classic/transfer-r1.ts)** - Complete implementation using secp256r1 keys for transfers with LiteSVM testing
* **[Interactive Passkey UI](https://github.com/anagrambuild/swig-ts/tree/main/examples/secp-ui)** - Full UI demonstration with passkey helper functions and user authentication flows. Key files:
  * [`passkey.ts`](https://github.com/anagrambuild/swig-ts/blob/main/examples/secp-ui/src/helpers/passkey.ts) - Core PasskeyManager implementation
  * [`passkey.tsx`](https://github.com/anagrambuild/swig-ts/blob/main/examples/secp-ui/src/hooks/passkey.tsx) - React hooks for passkey integration

## Overview

Swig Wallet supports WebAuthn passkeys through the secp256r1 elliptic curve, enabling users to authenticate using biometrics, security keys, or platform authenticators without requiring passwords or seed phrases.

## Key Components

### PasskeyManager Class

The `PasskeyManager` class provides a complete interface for creating, storing, and using passkeys:

```typescript theme={null}
import { PasskeyManager } from './helpers/passkey';
import { signWithSecp256r1Webauthn } from '@swig-wallet/classic';
```

Below is a compact, `PasskeyManager` implementation (create, sign, and stored credential helpers):

```typescript theme={null}
import {
  signWithSecp256r1Webauthn,
  type SigningResult,
} from '@swig-wallet/classic';

export interface PasskeyCredential {
  id: string;
  publicKey: Uint8Array;
  rawId: ArrayBuffer;
}

export class PasskeyManager {
  private static readonly STORAGE_KEY = 'swig-passkey-credential';

  /**
   * Create a new passkey credential for authentication
   */
  static createPasskey = async(
    username: string = 'swig-user',
  ): Promise<PasskeyCredential> => {
    if (!window.navigator.credentials) {
      throw new Error('WebAuthn not supported in this browser');
    }

    const challenge = crypto.getRandomValues(new Uint8Array(32));

    const publicKeyCredentialCreationOptions: PublicKeyCredentialCreationOptions =
      {
        challenge,
        rp: {
          name: 'Swig Wallet',
          id: window.location.hostname,
        },
        user: {
          id: crypto.getRandomValues(new Uint8Array(64)),
          name: username,
          displayName: username,
        },
        pubKeyCredParams: [
          {
            alg: -7, // ES256 (secp256r1 with SHA-256)
            type: 'public-key',
          },
        ],
        authenticatorSelection: {
          authenticatorAttachment: 'platform',
          userVerification: 'preferred',
          requireResidentKey: false,
        },
        timeout: 60000,
        attestation: 'direct',
      };

    const credential = (await navigator.credentials.create({
      publicKey: publicKeyCredentialCreationOptions,
    })) as PublicKeyCredential | null;

    if (!credential || !credential.response) {
      throw new Error('Failed to create passkey credential');
    }

    // Extract the public key from the attestation
    const response = credential.response as AuthenticatorAttestationResponse;

    const publicKey = this.spkiToCompressedPublicKey(response.getPublicKey()!);

    const passkeyCredential: PasskeyCredential = {
      id: credential.id,
      publicKey,
      rawId: credential.rawId,
    };

    // Store the credential for future use
    this.storeCredential(passkeyCredential);

    return passkeyCredential;
  }

  /**
   * Sign a message using the stored passkey
   */
  static signWithPasskey = async(
    messageHash: Uint8Array,
  ): Promise<SigningResult> => {
    const credential = this.getStoredCredential();
    if (!credential) {
      throw new Error('No passkey credential found. Please create one first.');
    }

    return signWithSecp256r1Webauthn({
      challenge: messageHash,
      allowCredentials: [
        {
          id: credential.rawId,
          type: 'public-key',
        },
      ],
      timeout: 60000,
      userVerification: 'preferred',
    });
  }

  static getStoredCredential = (): PasskeyCredential | null => {
    // Implementation details...
  }

  private static storeCredential = (credential: PasskeyCredential): void => {
    // Implementation details...
  }

  static clearStoredCredential = (): void => {
    // Implementation details...
  }

  static isSupported = (): boolean => {
    // Implementation details...
  }

  // ... additional helper methods
}
```

### Core Features

* **Passkey Creation**: Generate new WebAuthn credentials
* **Secure Storage**: Store credentials in browser localStorage
* **Message Signing**: Sign transactions using passkeys
* **Browser Support Detection**: Check WebAuthn compatibility

## Usage Guide

### 1. Check Browser Support

Before implementing passkeys, verify browser support:

```typescript theme={null}
if (PasskeyManager.isSupported()) {
  console.log('✅ WebAuthn is supported');
} else {
  console.log('❌ WebAuthn not supported');
}
```

### 2. Create a Passkey

Create a new passkey credential for a user:

```typescript theme={null}
try {
  const credential = await PasskeyManager.createPasskey('user@example.com');
  console.log('Passkey created:', credential.id);
  console.log('Public key:', credential.publicKey);
} catch (error) {
  console.error('Failed to create passkey:', error);
}
```

The `createPasskey` method:

* Uses ES256 algorithm (secp256r1 with SHA-256)
* Requires platform authenticator (built-in biometrics)
* Sets 60-second timeout
* Automatically stores the credential

### 3. Sign Messages with Passkeys

Use the stored passkey to sign transaction messages:

```typescript theme={null}
const messageHash = new Uint8Array(32); // Your message hash

try {
  const signingResult = await PasskeyManager.signWithPasskey(messageHash);
  console.log('Signature:', signingResult.signature);
  console.log('WebAuthn message:', signingResult.message);
  console.log('Prefix data:', signingResult.prefix);
} catch (error) {
  console.error('Failed to sign:', error);
}
```

### 4. Retrieve Stored Credentials

Access previously created passkey credentials:

```typescript theme={null}
const storedCredential = PasskeyManager.getStoredCredential();
if (storedCredential) {
  console.log('Found stored passkey:', storedCredential.id);
} else {
  console.log('No passkey found');
}
```

### 5. Clear Stored Credentials

Remove passkey data from storage:

```typescript theme={null}
PasskeyManager.clearStoredCredential();
console.log('Passkey cleared');
```

## Advanced Integration

### Custom Signing Function

Create a reusable signing function for your application:

```typescript theme={null}
import { getSecp256r1WebAuthnSigningFn } from '@swig-wallet/lib';

const credential = PasskeyManager.getStoredCredential();
if (credential) {
  const signingFn = getSecp256r1WebAuthnSigningFn({
    allowCredentials: [
      {
        id: credential.rawId,
        type: 'public-key',
      },
    ],
    timeout: 60000,
    userVerification: 'preferred',
  });
  
  // Use signingFn with Swig instructions
}
```

### Direct WebAuthn Integration

For advanced use cases, use the low-level WebAuthn functions:

```typescript theme={null}
import { signWithSecp256r1Webauthn } from '@swig-wallet/classic';

const signingResult = await signWithSecp256r1Webauthn({
  challenge: messageHash,
  allowCredentials: [
    {
      id: credentialId,
      type: 'public-key',
    },
  ],
  timeout: 60000,
  userVerification: 'preferred',
});
```

### Raw secp256r1 Keys (Testing & Development)

For testing without WebAuthn or when you need direct cryptographic control, use raw secp256r1 private keys:

```typescript theme={null}
import { p256 } from '@noble/curves/nist';
import {
  createSecp256r1AuthorityInfo,
  getSigningFnForSecp256r1PrivateKey,
  getCreateSwigInstruction,
  Actions,
} from '@swig-wallet/classic';

// Generate raw secp256r1 keypair
const userWallet = p256.keygen();
const publicKey = p256.getPublicKey(userWallet.secretKey, true); // compressed

// Create Swig authority with raw public key
const authorityInfo = createSecp256r1AuthorityInfo(publicKey);

// Create signing function with raw private key
const signingFn = getSigningFnForSecp256r1PrivateKey(userWallet.secretKey);

// Use with Swig instructions
const createSwigInstruction = await getCreateSwigInstruction({
  authorityInfo,
  id: new Uint8Array(32),
  payer: payerPublicKey,
  actions: Actions.set().all().get(),
});

// Sign transactions using raw key
const signedInstructions = await getSignInstructions(
  swig,
  roleId,
  [transferInstruction],
  false,
  {
    currentSlot: BigInt(currentSlot),
    signingFn,
    payer: payerPublicKey,
  },
);
```

**When to use raw secp256r1 keys:**

* Testing and development environments
* Server-side applications
* When WebAuthn is not available
* Automated scripts and tooling
* Non-browser environments

<Warning>
  **Security Note:** Raw private keys should never be used in production client applications. Always prefer WebAuthn passkeys for user-facing authentication.
</Warning>

## Technical Details

### Public Key Format

Passkeys use compressed secp256r1 public keys (33 bytes):

* 1 byte prefix (0x02 or 0x03)
* 32 bytes X-coordinate

The `PasskeyManager` automatically converts SPKI format to compressed format.

### Signature Format

WebAuthn signatures are:

* Raw 64-byte format (not DER encoded)
* Normalized S values (canonical signatures)
* Generated from `hash(authenticatorData + SHA256(clientDataJSON))`

### Authentication Data

The WebAuthn prefix includes:

* Authentication type identifier
* Authenticator data
* Client data field order
* Huffman-compressed origin URL
* Additional WebAuthn metadata

## Security Considerations

### Best Practices

1. **Verify Origin**: Passkeys are bound to your domain origin
2. **Timeout Handling**: Set appropriate timeouts for user experience
3. **Error Handling**: Gracefully handle user cancellation
4. **Fallback Options**: Provide alternative auth methods
5. **Secure Storage**: Credentials in localStorage are domain-isolated

### Browser Requirements

* Chrome 67+ / Safari 14+ / Firefox 60+
* HTTPS required (except localhost)
* Platform authenticator support varies by device

## Example Implementation

### WebAuthn Passkey Example

Here's a complete example integrating passkeys with Swig Wallet:

```typescript theme={null}
import { PasskeyManager } from './helpers/passkey';
import {
  createSecp256r1AuthorityInfo,
  getCreateSwigInstruction,
  Actions,
} from '@swig-wallet/classic';

async function setupSwigWithPasskey() {
  // Check support
  if (!PasskeyManager.isSupported()) {
    throw new Error('WebAuthn not supported');
  }

  // Create or retrieve passkey
  let credential = PasskeyManager.getStoredCredential();
  if (!credential) {
    credential = await PasskeyManager.createPasskey();
  }

  // Create Swig authority with passkey
  const authorityInfo = createSecp256r1AuthorityInfo(credential.publicKey);

  // Create Swig instruction
  const createSwigInstruction = await getCreateSwigInstruction({
    authorityInfo,
    id: new Uint8Array(32), // Your unique ID
    payer: payerPublicKey,
    actions: Actions.set().all().get(),
  });

  // Sign and send transaction...
}
```

### Raw secp256r1 Key Example (LiteSVM Testing)

For testing with LiteSVM or other development scenarios:

```typescript theme={null}
import { p256 } from '@noble/curves/nist';
import { LiteSVM } from 'litesvm';
import {
  createSecp256r1AuthorityInfo,
  getSigningFnForSecp256r1PrivateKey,
  findSwigPda,
  getCreateSwigInstruction,
  getSignInstructions,
  Swig,
  Actions,
} from '@swig-wallet/classic';

// Initialize SVM and generate keys
const svm = new LiteSVM();
const userWallet = p256.keygen();
const userKeypair = Keypair.generate();

// Setup Swig with secp256r1 authority
const swigAccountAddress = findSwigPda(new Uint8Array(32));
const createInstruction = await getCreateSwigInstruction({
  authorityInfo: createSecp256r1AuthorityInfo(userWallet.publicKey),
  id: new Uint8Array(32),
  payer: userKeypair.publicKey,
  actions: Actions.set().all().get(),
});

// Create signing function
const signingFn = getSigningFnForSecp256r1PrivateKey(userWallet.secretKey);

// Send transactions
svm.sendTransaction(new Transaction().add(createInstruction));

// Fetch Swig and get wallet address
const swig = await fetchSwig(svm, swigAccountAddress);
const swigWalletAddress = await getSwigWalletAddress(swig);

// Use for signing other instructions (use swigWalletAddress for transfers)
const signedTransfer = await getSignInstructions(
  swig,
  roleId,
  [
    SystemProgram.transfer({
      fromPubkey: swigWalletAddress,
      toPubkey: recipientAddress,
      lamports: 1_000_000,
    }),
  ],
  false,
  {
    currentSlot: svm.getClock().slot,
    signingFn,
    payer: userKeypair.publicKey,
  },
);
```

## Examples

Check out these working implementations:

<Card title="secp256r1 Transfer Example" icon="code" href="https://github.com/anagrambuild/swig-ts/blob/main/examples/basic/classic/transfer-r1.ts">
  Complete example using secp256r1 keys for transfers with LiteSVM testing
</Card>

<Card title="Passkey UI Example" icon="window" href="https://github.com/anagrambuild/swig-ts/tree/main/examples/secp-ui">
  Interactive UI demonstrating passkey integration with helper functions
</Card>

## Troubleshooting

### Common Issues

1. **"WebAuthn not supported"**: Browser lacks WebAuthn API
2. **"No authenticator available"**: Device lacks biometric/security key
3. **"User cancelled"**: User declined authentication prompt
4. **"Invalid domain"**: Origin mismatch or non-HTTPS context

### Debug Tips

* Test on multiple devices and browsers
* Check browser console for detailed WebAuthn errors
* Verify HTTPS in production environments
* Test with different authenticator types

## Resources

* [Swig secp256r1 Authority Documentation](secp256r1_authority)
* [Swig Passkey UI Example](https://github.com/anagrambuild/swig-ts/tree/main/examples/secp-ui) - Interactive UI implementation with passkey helpers


# Advanced Paymaster Usage
Source: https://build.onswig.com/examples/paymaster/advanced-usage

"Production-ready patterns for paymaster integration" - Swig Engineering

This guide covers advanced topics for using the Swig Paymaster SDK in production applications.

## Versioned Transactions with Lookup Tables

Address lookup tables (ALTs) allow you to fit more accounts in a single transaction by referencing them via a compact index.

<Note>
  Lookup tables are only supported in the Classic SDK via `createTransaction()`. The Kit SDK always creates versioned transactions.
</Note>

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

const paymaster = createPaymasterClient({
  apiKey: process.env.SWIG_API_KEY!,
  paymasterPubkey: process.env.PAYMASTER_PUBKEY!,
  baseUrl: 'https://api.onswig.com',
  network: 'mainnet',
});

const userKeypair = Keypair.generate();

// Your address lookup table
const lookupTableAddress = new PublicKey('YourLookupTableAddress...');

// Complex instruction with many accounts
const complexInstruction = createComplexInstruction(/* ... */);

// Create versioned transaction with lookup tables
const transaction = await paymaster.createTransaction(
  [complexInstruction],
  [userKeypair],
  [lookupTableAddress], // Address lookup tables
);

const signature = await paymaster.signAndSend(transaction);
```

### When to Use Lookup Tables

* Transactions with more than 32 accounts
* DeFi operations involving multiple programs
* Batch operations with repeated addresses

## Error Handling

### PaymasterError

The SDK throws `PaymasterError` for API-related failures:

```typescript theme={null}
import { PaymasterError } from '@swig-wallet/paymaster-core';

try {
  const signature = await paymaster.signAndSend(transaction);
  console.log('Success:', signature);
} catch (error) {
  if (error instanceof PaymasterError) {
    console.error('Paymaster Error:');
    console.error('  Status:', error.statusCode);
    console.error('  Message:', error.message);
    console.error('  Response:', error.response);

    // Handle specific status codes
    switch (error.statusCode) {
      case 400:
        console.error('Invalid transaction');
        break;
      case 401:
        console.error('Invalid API key');
        break;
      case 402:
        console.error('Paymaster has insufficient balance');
        break;
      case 429:
        console.error('Rate limited - try again later');
        break;
      case 500:
        console.error('Server error - retry with backoff');
        break;
    }
  } else {
    // Handle non-paymaster errors (network issues, etc.)
    throw error;
  }
}
```

### Common Error Scenarios

| Status Code | Cause                          | Solution                                   |
| ----------- | ------------------------------ | ------------------------------------------ |
| 400         | Invalid transaction format     | Check transaction structure and signatures |
| 401         | Invalid or expired API key     | Regenerate API key in Developer Portal     |
| 402         | Insufficient paymaster balance | Fund your paymaster with SOL               |
| 403         | Transaction exceeds limits     | Check single TX limit or monthly threshold |
| 429         | Rate limit exceeded            | Implement backoff, consider upgrading tier |
| 500         | Server error                   | Retry with exponential backoff             |

## Retry Configuration

Configure automatic retries when creating the client:

```typescript theme={null}
const paymaster = createPaymasterClient({
  apiKey: process.env.SWIG_API_KEY!,
  paymasterPubkey: process.env.PAYMASTER_PUBKEY!,
  baseUrl: 'https://api.onswig.com',
  network: 'mainnet',
  retryOptions: {
    maxRetries: 3,        // Number of retry attempts
    retryDelay: 1000,     // Initial delay (1 second)
    backoffMultiplier: 2, // Exponential backoff
  },
});
```

### How Retries Work

With the configuration above:

* **Attempt 1**: Immediate
* **Attempt 2**: After 1 second (1000ms)
* **Attempt 3**: After 2 seconds (1000ms × 2)
* **Attempt 4**: After 4 seconds (1000ms × 2 × 2)

### Production Recommendations

```typescript theme={null}
// Production configuration
const paymaster = createPaymasterClient({
  apiKey: process.env.SWIG_API_KEY!,
  paymasterPubkey: process.env.PAYMASTER_PUBKEY!,
  baseUrl: 'https://api.onswig.com',
  network: 'mainnet',
  retryOptions: {
    maxRetries: 5,
    retryDelay: 500,
    backoffMultiplier: 2,
  },
});
```

## Sign Without Sending

Sometimes you need to inspect or store a signed transaction before sending:

<Tabs>
  <Tab title="Classic (web3.js 1.x)">
    ```typescript theme={null}
    // Create and user-sign the transaction
    const transaction = await paymaster.createLegacyTransaction(
      [instruction],
      [userKeypair],
    );

    // Get paymaster signature without sending
    const signedTx = await paymaster.sign(transaction);

    // Inspect the transaction
    console.log('Signatures:', signedTx.signatures.length);
    console.log('Fee payer:', signedTx.feePayer?.toBase58());
    console.log('Instructions:', signedTx.instructions.length);

    // Serialize for storage or later sending
    const serialized = signedTx.serialize();
    console.log('Serialized size:', serialized.length, 'bytes');

    // Send manually later
    const connection = new Connection('https://api.mainnet-beta.solana.com');
    const signature = await connection.sendRawTransaction(serialized);
    await connection.confirmTransaction(signature);
    ```
  </Tab>

  <Tab title="Kit (web3.js 2.0)">
    ```typescript theme={null}
    import {
      partiallySignTransaction,
      getTransactionCodec,
      sendTransaction,
    } from '@solana/kit';

    // Create transaction
    const unsignedTx = await paymaster.createTransaction([instruction]);

    // User signs
    const partiallySignedTx = await partiallySignTransaction(
      [userKeypair.keyPair],
      unsignedTx,
    );

    // Get paymaster signature without sending
    const signedTx = await paymaster.sign(partiallySignedTx);

    // Inspect the transaction
    const codec = getTransactionCodec();
    const serialized = codec.encode(signedTx);
    console.log('Serialized size:', serialized.length, 'bytes');

    // Send manually later
    const signature = await sendTransaction(rpc)(signedTx);
    ```
  </Tab>
</Tabs>

## Transaction Message Signing (Kit Only)

The Kit SDK supports signing from a transaction message directly:

```typescript theme={null}
import {
  createTransactionMessage,
  setTransactionMessageFeePayer,
  setTransactionMessageLifetimeUsingBlockhash,
  appendTransactionMessageInstructions,
  pipe,
} from '@solana/kit';
import { createPaymasterClient } from '@swig-wallet/paymaster-kit';

const paymaster = createPaymasterClient({
  apiKey: process.env.SWIG_API_KEY!,
  paymasterPubkey: address(process.env.PAYMASTER_PUBKEY!),
  baseUrl: 'https://api.onswig.com',
  network: 'devnet',
});

// Get blockhash
const { value: latestBlockhash } = await rpc.getLatestBlockhash().send();

// Build transaction message manually
const txMessage = pipe(
  createTransactionMessage({ version: 0 }),
  (tx) => setTransactionMessageFeePayer(paymasterPubkey, tx),
  (tx) => setTransactionMessageLifetimeUsingBlockhash(latestBlockhash, tx),
  (tx) => appendTransactionMessageInstructions([instruction], tx),
);

// Sign the message directly
const signedTx = await paymaster.signTransactionMessage(txMessage);
```

## Serialized Transaction Methods

For low-level control, work directly with serialized bytes:

```typescript theme={null}
// Sign serialized transaction
const serializedUnsigned = transaction.serialize({ requireAllSignatures: false });
const serializedSigned = await paymaster.signSerializedTransaction(
  new Uint8Array(serializedUnsigned),
);

// Sign and send serialized transaction
const signature = await paymaster.signAndSendSerializedTransaction(
  new Uint8Array(serializedUnsigned),
);
```

## Environment-Specific Configuration

### Development

```typescript theme={null}
const paymaster = createPaymasterClient({
  apiKey: process.env.SWIG_API_KEY_DEV!,
  paymasterPubkey: process.env.PAYMASTER_PUBKEY_DEV!,
  baseUrl: 'https://api.onswig.com',
  network: 'devnet',
  // No retries in dev for faster feedback
});
```

### Staging

```typescript theme={null}
const paymaster = createPaymasterClient({
  apiKey: process.env.SWIG_API_KEY_STAGING!,
  paymasterPubkey: process.env.PAYMASTER_PUBKEY_STAGING!,
  baseUrl: 'https://api.onswig.com',
  network: 'devnet',
  retryOptions: {
    maxRetries: 2,
    retryDelay: 500,
    backoffMultiplier: 2,
  },
});
```

### Production

```typescript theme={null}
const paymaster = createPaymasterClient({
  apiKey: process.env.SWIG_API_KEY_PROD!,
  paymasterPubkey: process.env.PAYMASTER_PUBKEY_PROD!,
  baseUrl: 'https://api.onswig.com',
  network: 'mainnet',
  customRpcUrl: process.env.CUSTOM_RPC_URL, // Use dedicated RPC
  retryOptions: {
    maxRetries: 5,
    retryDelay: 500,
    backoffMultiplier: 2,
  },
});
```

## Next Steps

* [Manage Paymasters](/examples/dev-portal/manage-paymaster) - Configure limits and settings
* [Transaction History](/examples/dev-portal/transaction-history) - View analytics
* [Error Codes](/examples/dev-portal/error-codes) - Full error reference


# Using Paymaster SDK
Source: https://build.onswig.com/examples/paymaster/index

"Gasless transactions for seamless user experiences" - Swig Engineering

This guide covers how to use the Swig Paymaster SDK to sponsor transaction fees for your users, enabling gasless transactions.

## What is a Paymaster?

A paymaster is a service that pays transaction fees on behalf of users. Instead of requiring users to hold SOL for gas fees, the paymaster covers these costs, creating a seamless onboarding experience.

**Benefits:**

* Users don't need SOL for transaction fees
* Lower barrier to entry for new users
* Better user experience for dApps

## Prerequisites

Before using the paymaster SDK:

1. **Create a paymaster** in the [Developer Portal](https://dashboard.onswig.com)
2. **Fund your paymaster** with SOL
3. **Get your API key** from the Developer Portal

<Note>
  Paymasters require a paid subscription (PRO, ULTRA, or ENTERPRISE). See [Subscriptions & Billing](/examples/dev-portal/subscriptions-billing) for details.
</Note>

## Installation

Choose the package that matches your Solana SDK version:

<Tabs>
  <Tab title="Classic (web3.js 1.x)">
    ```bash theme={null}
    npm install @swig-wallet/paymaster-classic
    ```

    For applications using `@solana/web3.js` version 1.x (the traditional Solana SDK).
  </Tab>

  <Tab title="Kit (web3.js 2.0)">
    ```bash theme={null}
    npm install @swig-wallet/paymaster-kit
    ```

    For applications using `@solana/kit` (the new modular Solana SDK 2.0).
  </Tab>
</Tabs>

## Configuration

Create a paymaster client with your credentials:

<Tabs>
  <Tab title="Classic (web3.js 1.x)">
    ```typescript theme={null}
    import { createPaymasterClient } from '@swig-wallet/paymaster-classic';

    const paymaster = createPaymasterClient({
      apiKey: process.env.SWIG_API_KEY!,
      paymasterPubkey: process.env.PAYMASTER_PUBKEY!,
      baseUrl: 'https://api.onswig.com',
      network: 'devnet',
    });
    ```
  </Tab>

  <Tab title="Kit (web3.js 2.0)">
    ```typescript theme={null}
    import { createPaymasterClient } from '@swig-wallet/paymaster-kit';
    import { address } from '@solana/kit';

    const paymaster = createPaymasterClient({
      apiKey: process.env.SWIG_API_KEY!,
      paymasterPubkey: address(process.env.PAYMASTER_PUBKEY!),
      baseUrl: 'https://api.onswig.com',
      network: 'devnet',
    });
    ```
  </Tab>
</Tabs>

### Configuration Options

| Option            | Type                      | Required | Description                                  |
| ----------------- | ------------------------- | -------- | -------------------------------------------- |
| `apiKey`          | string                    | Yes      | API key from Developer Portal                |
| `paymasterPubkey` | string                    | Yes      | Paymaster public key                         |
| `baseUrl`         | string                    | Yes      | Paymaster API URL (`https://api.onswig.com`) |
| `network`         | `'mainnet'` \| `'devnet'` | Yes      | Solana network                               |
| `customRpcUrl`    | string                    | No       | Custom RPC endpoint (overrides default)      |
| `retryOptions`    | object                    | No       | Retry configuration for failed requests      |

### Retry Options

Configure automatic retries for transient failures:

```typescript theme={null}
const paymaster = createPaymasterClient({
  apiKey: 'sk_your_api_key',
  paymasterPubkey: '...',
  baseUrl: 'https://api.onswig.com',
  network: 'mainnet',
  retryOptions: {
    maxRetries: 3,        // Number of retry attempts
    retryDelay: 1000,     // Initial delay in milliseconds
    backoffMultiplier: 2, // Exponential backoff multiplier
  },
});
```

## Quick Start

Here's a minimal example to sponsor a transaction:

<Tabs>
  <Tab title="Classic (web3.js 1.x)">
    ```typescript theme={null}
    import { Keypair, PublicKey, TransactionInstruction } from '@solana/web3.js';
    import { createPaymasterClient } from '@swig-wallet/paymaster-classic';

    // Initialize client
    const paymaster = createPaymasterClient({
      apiKey: process.env.SWIG_API_KEY!,
      paymasterPubkey: process.env.PAYMASTER_PUBKEY!,
      baseUrl: 'https://api.onswig.com',
      network: 'devnet',
    });

    // User's keypair
    const userKeypair = Keypair.generate();

    // Create an instruction (memo example)
    const instruction = new TransactionInstruction({
      keys: [{ pubkey: userKeypair.publicKey, isSigner: true, isWritable: false }],
      programId: new PublicKey('MemoSq4gqABAXKb96qnH8TysNcWxMyWCqXgDLGmfcHr'),
      data: Buffer.from('Hello, gasless world!'),
    });

    // Create transaction - paymaster is set as fee payer
    const transaction = await paymaster.createLegacyTransaction(
      [instruction],
      [userKeypair], // User signs here
    );

    // Paymaster signs and sends
    const signature = await paymaster.signAndSend(transaction);
    console.log(`https://explorer.solana.com/tx/${signature}?cluster=devnet`);
    ```
  </Tab>

  <Tab title="Kit (web3.js 2.0)">
    ```typescript theme={null}
    import { getAddMemoInstruction } from '@solana-program/memo';
    import {
      address,
      generateKeyPairSigner,
      getSignatureFromTransaction,
      partiallySignTransaction,
    } from '@solana/kit';
    import { createPaymasterClient } from '@swig-wallet/paymaster-kit';

    // Initialize client
    const paymaster = createPaymasterClient({
      apiKey: process.env.SWIG_API_KEY!,
      paymasterPubkey: address(process.env.PAYMASTER_PUBKEY!),
      baseUrl: 'https://api.onswig.com',
      network: 'devnet',
    });

    // User's keypair
    const userKeypair = await generateKeyPairSigner();

    // Create an instruction
    const instruction = getAddMemoInstruction({
      memo: 'Hello, gasless world!',
      signers: [userKeypair],
    });

    // Create transaction - paymaster is set as fee payer
    const unsignedTx = await paymaster.createTransaction([instruction]);

    // User signs
    const partiallySignedTx = await partiallySignTransaction(
      [userKeypair.keyPair],
      unsignedTx,
    );

    // Paymaster signs and validates
    const signedTx = await paymaster.fullySign(partiallySignedTx);

    // Get signature
    const signature = getSignatureFromTransaction(signedTx).toString();
    console.log(`https://explorer.solana.com/tx/${signature}?cluster=devnet`);
    ```
  </Tab>
</Tabs>

## Transaction Flow

The paymaster transaction flow works as follows:

```
┌─────────────┐    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│   Create    │───▶│    User     │───▶│  Paymaster  │───▶│   Submit    │
│ Transaction │    │    Signs    │    │    Signs    │    │  to Network │
└─────────────┘    └─────────────┘    └─────────────┘    └─────────────┘
       │                  │                  │                  │
       ▼                  ▼                  ▼                  ▼
   Paymaster         User proves       Fee covered        Transaction
   as fee payer     authorization      by paymaster        confirmed
```

1. **Create Transaction**: Build the transaction with the paymaster set as the fee payer
2. **User Signs**: User signs to authorize the transaction
3. **Paymaster Signs**: Paymaster validates and signs (covering the fee)
4. **Submit**: Transaction is sent to the Solana network

## Next Steps

* [Sponsoring Transactions](./sponsor-transactions) - Detailed examples and methods
* [Advanced Usage](./advanced-usage) - Error handling, retries, versioned transactions
* [Create a Paymaster](/examples/dev-portal/create-paymaster) - Set up your paymaster in the Developer Portal


# Sponsoring Transactions
Source: https://build.onswig.com/examples/paymaster/sponsor-transactions

"Let your users transact without worrying about gas" - Swig Engineering

This guide covers how to create, sign, and send sponsored transactions using the Swig Paymaster SDK.

## Available Methods

The paymaster client provides several methods for working with transactions:

| Method              | Classic                     | Kit                   | Description                           |
| ------------------- | --------------------------- | --------------------- | ------------------------------------- |
| Create legacy tx    | `createLegacyTransaction()` | N/A                   | Legacy transaction (no lookup tables) |
| Create versioned tx | `createTransaction()`       | `createTransaction()` | Versioned v0 transaction              |
| Sign only           | `sign()`                    | `sign()`              | Sign without sending                  |
| Sign + validate     | N/A                         | `fullySign()`         | Sign and assert fully signed          |
| Sign + send         | `signAndSend()`             | `signAndSend()`       | Sign and submit to network            |

## Creating Transactions

### Legacy Transactions (Classic Only)

Legacy transactions are simpler but don't support address lookup tables:

```typescript theme={null}
import { Keypair, PublicKey, SystemProgram } from '@solana/web3.js';
import { createPaymasterClient } from '@swig-wallet/paymaster-classic';

const paymaster = createPaymasterClient({
  apiKey: process.env.SWIG_API_KEY!,
  paymasterPubkey: process.env.PAYMASTER_PUBKEY!,
  baseUrl: 'https://api.onswig.com',
  network: 'devnet',
});

const sender = Keypair.generate();
const recipient = new PublicKey('...');

// Create a SOL transfer instruction
const transferInstruction = SystemProgram.transfer({
  fromPubkey: sender.publicKey,
  toPubkey: recipient,
  lamports: 1_000_000, // 0.001 SOL
});

// Create legacy transaction with user signing
const transaction = await paymaster.createLegacyTransaction(
  [transferInstruction],
  [sender], // Signers
);
```

### Versioned Transactions

Versioned transactions (v0) support address lookup tables for more efficient transactions:

<Tabs>
  <Tab title="Classic (web3.js 1.x)">
    ```typescript theme={null}
    import { Keypair, PublicKey, SystemProgram } from '@solana/web3.js';
    import { createPaymasterClient } from '@swig-wallet/paymaster-classic';

    const paymaster = createPaymasterClient({
      apiKey: process.env.SWIG_API_KEY!,
      paymasterPubkey: process.env.PAYMASTER_PUBKEY!,
      baseUrl: 'https://api.onswig.com',
      network: 'devnet',
    });

    const sender = Keypair.generate();

    const instruction = SystemProgram.transfer({
      fromPubkey: sender.publicKey,
      toPubkey: new PublicKey('...'),
      lamports: 1_000_000,
    });

    // Create versioned transaction (v0)
    const transaction = await paymaster.createTransaction(
      [instruction],
      [sender],
      // Optional: address lookup tables
      // [lookupTableAddress]
    );
    ```
  </Tab>

  <Tab title="Kit (web3.js 2.0)">
    ```typescript theme={null}
    import { address, generateKeyPairSigner } from '@solana/kit';
    import { getTransferSolInstruction } from '@solana-program/system';
    import { createPaymasterClient } from '@swig-wallet/paymaster-kit';

    const paymaster = createPaymasterClient({
      apiKey: process.env.SWIG_API_KEY!,
      paymasterPubkey: address(process.env.PAYMASTER_PUBKEY!),
      baseUrl: 'https://api.onswig.com',
      network: 'devnet',
    });

    const sender = await generateKeyPairSigner();

    const instruction = getTransferSolInstruction({
      source: sender,
      destination: address('...'),
      amount: 1_000_000n, // 0.001 SOL
    });

    // Create versioned transaction
    const transaction = await paymaster.createTransaction([instruction]);
    ```
  </Tab>
</Tabs>

## Signing Transactions

### Sign and Send (Recommended)

The simplest approach - sign and submit in one call:

<Tabs>
  <Tab title="Classic (web3.js 1.x)">
    ```typescript theme={null}
    // Create transaction with user signing
    const transaction = await paymaster.createLegacyTransaction(
      [instruction],
      [userKeypair],
    );

    // Paymaster signs and submits
    const signature = await paymaster.signAndSend(transaction);
    console.log(`Transaction: https://explorer.solana.com/tx/${signature}`);
    ```
  </Tab>

  <Tab title="Kit (web3.js 2.0)">
    ```typescript theme={null}
    import { partiallySignTransaction } from '@solana/kit';

    // Create transaction
    const unsignedTx = await paymaster.createTransaction([instruction]);

    // User signs
    const partiallySignedTx = await partiallySignTransaction(
      [userKeypair.keyPair],
      unsignedTx,
    );

    // Paymaster signs and validates
    const signedTx = await paymaster.fullySign(partiallySignedTx);

    // Send using your own RPC connection
    await sendAndConfirmTransaction(connection)(signedTx);
    ```
  </Tab>
</Tabs>

### Sign Only (For Inspection)

Sign without sending - useful for inspecting the transaction before submission:

<Tabs>
  <Tab title="Classic (web3.js 1.x)">
    ```typescript theme={null}
    const transaction = await paymaster.createLegacyTransaction(
      [instruction],
      [userKeypair],
    );

    // Get signed transaction without sending
    const signedTx = await paymaster.sign(transaction);

    // Inspect the transaction
    console.log('Signatures:', signedTx.signatures);
    console.log('Fee payer:', signedTx.feePayer?.toBase58());

    // Send manually when ready
    const signature = await connection.sendRawTransaction(signedTx.serialize());
    ```
  </Tab>

  <Tab title="Kit (web3.js 2.0)">
    ```typescript theme={null}
    import { partiallySignTransaction, getTransactionCodec } from '@solana/kit';

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

    // Get signed transaction without sending
    const signedTx = await paymaster.sign(partiallySignedTx);

    // Inspect the transaction
    const codec = getTransactionCodec();
    console.log('Transaction bytes:', codec.encode(signedTx));

    // Send manually when ready
    ```
  </Tab>
</Tabs>

### Full Signature Validation (Kit Only)

The Kit SDK provides `fullySign()` which validates that all required signatures are present:

```typescript theme={null}
import { partiallySignTransaction, assertIsFullySignedTransaction } from '@solana/kit';

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

// Sign and validate all signatures are present
const fullySignedTx = await paymaster.fullySign(partiallySignedTx);

// TypeScript knows this is fully signed
// No need to call assertIsFullySignedTransaction()
```

## Complete Examples

### SOL Transfer with Memo

<Tabs>
  <Tab title="Classic (web3.js 1.x)">
    ```typescript theme={null}
    import {
      Keypair,
      PublicKey,
      SystemProgram,
      TransactionInstruction,
    } from '@solana/web3.js';
    import { createPaymasterClient } from '@swig-wallet/paymaster-classic';

    const paymaster = createPaymasterClient({
      apiKey: process.env.SWIG_API_KEY!,
      paymasterPubkey: process.env.PAYMASTER_PUBKEY!,
      baseUrl: 'https://api.onswig.com',
      network: 'devnet',
    });

    const sender = Keypair.generate();
    const recipient = new PublicKey('RecipientAddressHere...');

    // SOL transfer instruction
    const transferIx = SystemProgram.transfer({
      fromPubkey: sender.publicKey,
      toPubkey: recipient,
      lamports: 10_000_000, // 0.01 SOL
    });

    // Memo instruction
    const memoIx = new TransactionInstruction({
      keys: [{ pubkey: sender.publicKey, isSigner: true, isWritable: false }],
      programId: new PublicKey('MemoSq4gqABAXKb96qnH8TysNcWxMyWCqXgDLGmfcHr'),
      data: Buffer.from('Payment for services'),
    });

    // Create transaction with both instructions
    const transaction = await paymaster.createLegacyTransaction(
      [transferIx, memoIx],
      [sender],
    );

    // Sign and send
    const signature = await paymaster.signAndSend(transaction);
    console.log(`Success: https://explorer.solana.com/tx/${signature}?cluster=devnet`);
    ```
  </Tab>

  <Tab title="Kit (web3.js 2.0)">
    ```typescript theme={null}
    import {
      address,
      generateKeyPairSigner,
      getSignatureFromTransaction,
      partiallySignTransaction,
      createSolanaRpc,
      createSolanaRpcSubscriptions,
      sendAndConfirmTransactionFactory,
    } from '@solana/kit';
    import { getTransferSolInstruction } from '@solana-program/system';
    import { getAddMemoInstruction } from '@solana-program/memo';
    import { createPaymasterClient } from '@swig-wallet/paymaster-kit';

    const paymaster = createPaymasterClient({
      apiKey: process.env.SWIG_API_KEY!,
      paymasterPubkey: address(process.env.PAYMASTER_PUBKEY!),
      baseUrl: 'https://api.onswig.com',
      network: 'devnet',
    });

    // Set up RPC for sending
    const rpc = createSolanaRpc('https://api.devnet.solana.com');
    const rpcSubscriptions = createSolanaRpcSubscriptions('wss://api.devnet.solana.com');
    const sendAndConfirm = sendAndConfirmTransactionFactory({ rpc, rpcSubscriptions });

    const sender = await generateKeyPairSigner();
    const recipient = address('RecipientAddressHere...');

    // SOL transfer instruction
    const transferIx = getTransferSolInstruction({
      source: sender,
      destination: recipient,
      amount: 10_000_000n, // 0.01 SOL
    });

    // Memo instruction
    const memoIx = getAddMemoInstruction({
      memo: 'Payment for services',
      signers: [sender],
    });

    // Create transaction
    const unsignedTx = await paymaster.createTransaction([transferIx, memoIx]);

    // User signs
    const partiallySignedTx = await partiallySignTransaction(
      [sender.keyPair],
      unsignedTx,
    );

    // Paymaster signs
    const signedTx = await paymaster.fullySign(partiallySignedTx);

    // Send and confirm
    await sendAndConfirm(signedTx, { commitment: 'confirmed' });

    const signature = getSignatureFromTransaction(signedTx).toString();
    console.log(`Success: https://explorer.solana.com/tx/${signature}?cluster=devnet`);
    ```
  </Tab>
</Tabs>

### Multiple Signers

When a transaction requires multiple user signatures:

<Tabs>
  <Tab title="Classic (web3.js 1.x)">
    ```typescript theme={null}
    const user1 = Keypair.generate();
    const user2 = Keypair.generate();

    // Instruction requiring both signatures
    const multiSigInstruction = new TransactionInstruction({
      keys: [
        { pubkey: user1.publicKey, isSigner: true, isWritable: true },
        { pubkey: user2.publicKey, isSigner: true, isWritable: false },
      ],
      programId: PROGRAM_ID,
      data: Buffer.from([...]),
    });

    // Both users sign
    const transaction = await paymaster.createLegacyTransaction(
      [multiSigInstruction],
      [user1, user2], // Multiple signers
    );

    const signature = await paymaster.signAndSend(transaction);
    ```
  </Tab>

  <Tab title="Kit (web3.js 2.0)">
    ```typescript theme={null}
    const user1 = await generateKeyPairSigner();
    const user2 = await generateKeyPairSigner();

    // Create transaction
    const unsignedTx = await paymaster.createTransaction([multiSigInstruction]);

    // Both users sign
    const partiallySignedTx = await partiallySignTransaction(
      [user1.keyPair, user2.keyPair],
      unsignedTx,
    );

    // Paymaster signs
    const signedTx = await paymaster.fullySign(partiallySignedTx);
    ```
  </Tab>
</Tabs>

## Best Practices

<CardGroup>
  <Card title="Test on Devnet First" icon="flask">
    Always test your integration on devnet before deploying to mainnet. Create a separate devnet paymaster for testing.
  </Card>

  <Card title="Handle Errors Gracefully" icon="shield">
    Wrap paymaster calls in try-catch and handle errors appropriately. See [Advanced Usage](./advanced-usage) for error handling patterns.
  </Card>

  <Card title="Monitor Your Balance" icon="chart-line">
    Keep your paymaster funded. Set up alerts in the Developer Portal to avoid running out of SOL.
  </Card>

  <Card title="Use Retry Options" icon="rotate">
    Configure retry options for production to handle transient network issues automatically.
  </Card>
</CardGroup>

## Next Steps

* [Advanced Usage](./advanced-usage) - Error handling, retries, versioned transactions
* [Manage Paymasters](/examples/dev-portal/manage-paymaster) - Monitor and manage your paymaster
* [Transaction History](/examples/dev-portal/transaction-history) - View sponsored transactions


# Using Secp256r1 (P-256) Authorities in Swig
Source: https://build.onswig.com/examples/secp256r1_authority

How to use P-256 (secp256r1) keys for secure, passkey-compatible authorization in Swig.

Secp256r1 (also known as P-256) is a widely adopted elliptic curve for public-key cryptography, supported by most modern cryptographic libraries and hardware.
It is defined by parameters: prime p, coefficients a and b, base point G, and its prime order n.
Unlike native Ed25519, secp256r1 requires a precompiled program for signature verification.

## Why use Secp256r1 with Swig?

* Native support for passkeys and hardware-backed authentication
* Secure, standards-based cryptography
* Compatible with modern browsers and devices
* Enables session-based authorities for limited-lifetime delegation

## Technical Overview

Secp256r1 for SWIG Wallet:

**Secp256r1 Authority**: Represents an account or role that can sign transactions using a Secp256r1 key.

**Session Authority:** Supports session-based authorities for limited-lifetime delegation.

**Signature Odometer:** Each authority tracks a counter to prevent replay attacks.

### How to Use Secp256r1 Authority

The walkthrough covers both Rust and TypeScript implementations:

1. Key Generation
2. Authority Management
3. Transaction Signing & Replay Protection
4. Session Authorities

## TypeScript Implementation

### Key Generation & Basic Usage

Here's a complete TypeScript example using secp256r1 keys with Swig Wallet:

```typescript theme={null}
import { p256 } from '@noble/curves/nist';
import { Keypair, SystemProgram, Transaction } from '@solana/web3.js';
import { LiteSVM } from 'litesvm';
import {
  createSecp256r1AuthorityInfo,
  getSigningFnForSecp256r1PrivateKey,
  findSwigPda,
  getCreateSwigInstruction,
  getSignInstructions,
  getSwigWalletAddress,
  Swig,
  Actions,
} from '@swig-wallet/classic';

async function setupSecp256r1Transfer() {
  // 1. Initialize test environment
  const svm = new LiteSVM();
  
  // 2. Generate secp256r1 keypair
  const userWallet = p256.keygen();
  const publicKey = p256.getPublicKey(userWallet.secretKey, true); // compressed
  
  // 3. Generate Solana keypair for paying fees
  const userKeypair = Keypair.generate();
  const recipientKeypair = Keypair.generate();
  
  // Fund the payer
  svm.airdrop(userKeypair.publicKey, 1000000000); // 1 SOL
  
  // 4. Create Swig authority info
  const authorityInfo = createSecp256r1AuthorityInfo(publicKey);
  
  // 5. Find Swig PDA
  const swigId = new Uint8Array(32);
  const [swigAccountAddress] = findSwigPda(swigId);
  
  // 6. Create Swig account
  const createSwigInstruction = await getCreateSwigInstruction({
    authorityInfo,
    id: swigId,
    payer: userKeypair.publicKey,
    actions: Actions.set().all().get(),
  });
  
  // Send creation transaction
  const createTx = new Transaction().add(createSwigInstruction);
  svm.sendTransaction(createTx, [userKeypair]);
  
  // 7. Create signing function
  const signingFn = getSigningFnForSecp256r1PrivateKey(userWallet.secretKey);
  
  // 8. Load the created Swig and get wallet address
  const swig = await Swig.fromAccountAddress(svm, swigAccountAddress);
  const swigWalletAddress = await getSwigWalletAddress(swig);
  
  // 9. Create transfer instruction (use swigWalletAddress)
  const transferInstruction = SystemProgram.transfer({
    fromPubkey: swigWalletAddress,
    toPubkey: recipientKeypair.publicKey,
    lamports: 1000000, // 0.001 SOL
  });
  
  // 10. Sign the transfer using secp256r1
  const signedInstructions = await getSignInstructions(
    swig,
    0, // role ID
    [transferInstruction],
    false,
    {
      currentSlot: svm.getClock().slot,
      signingFn,
      payer: userKeypair.publicKey,
    }
  );
  
  // 11. Execute the signed transaction
  const signedTx = new Transaction().add(...signedInstructions);
  const result = svm.sendTransaction(signedTx, [userKeypair]);
  
  console.log('Transfer completed:', result);
  
  return {
    swigAddress,
    userWallet,
    signingFn,
    swig
  };
}
```

### WebAuthn Passkey Integration

For browser-based applications, you can integrate WebAuthn passkeys:

```typescript theme={null}
import { PasskeyManager } from './helpers/passkey';
import {
  createSecp256r1AuthorityInfo,
  getSecp256r1WebAuthnSigningFn,
} from '@swig-wallet/classic';

async function setupPasskeyAuth() {
  // Check WebAuthn support
  if (!PasskeyManager.isSupported()) {
    throw new Error('WebAuthn not supported in this browser');
  }
  
  // Create or retrieve passkey
  let credential = PasskeyManager.getStoredCredential();
  if (!credential) {
    credential = await PasskeyManager.createPasskey('user@example.com');
  }
  
  // Create authority info from passkey
  const authorityInfo = createSecp256r1AuthorityInfo(credential.publicKey);
  
  // Create WebAuthn signing function
  const signingFn = getSecp256r1WebAuthnSigningFn({
    allowCredentials: [{
      id: credential.rawId,
      type: 'public-key',
    }],
    timeout: 60000,
    userVerification: 'preferred',
  });
  
  return { authorityInfo, signingFn };
}
```

## Rust Implementation

#### A. Key Generation:

To use Secp256r1, a valid key pair is needed. A **create\_secp256r1\_keypair** function handles this using the **openssl** crate.

* **Curve:** It uses the **Nid::X9\_62\_PRIME256V1** curve, which is the standard for P-256.
* **Public Key Format:** The public key is serialized into a **33-byte compressed format**. This is crucial, as it's the format the on-chain program expects.

```rust theme={null}
/// Helper to generate a real secp256r1 key pair for testing
fn create_test_secp256r1_keypair() -> (openssl::ec::EcKey<openssl::pkey::Private>, [u8; 33]) {
    use openssl::{
        bn::BigNumContext,
        ec::{EcGroup, EcKey, PointConversionForm},
        nid::Nid,
    };

    // 1. Select the P-256 curve
    let group = EcGroup::from_curve_name(Nid::X9_62_PRIME256V1).unwrap();

    // 2. Generate the private/public key pair
    let signing_key = EcKey::generate(&group).unwrap();
    let mut ctx = BigNumContext::new().unwrap();

    // 3. Serialize the public key to its 33-byte compressed format
    let pubkey_bytes = signing_key
        .public_key()
        .to_bytes(&group, PointConversionForm::COMPRESSED, &mut ctx)
        .unwrap();
    let pubkey_array: [u8; 33] = pubkey_bytes.try_into().unwrap();

    (signing_key, pubkey_array)
}
```

#### B. Authority Management:

A SWIG account can be created with a **secp256r1** key as its primary authority or have one added later. This gives the **secp256r1** key holder control over the account.

For creating an Account with a **secp256r1** Authority, the **create\_swig\_secp256r1** function shows how to initialize a new swig account where a **secp256r1** public key is the owner.

```rust theme={null}
/// Helper function to create a swig account with secp256r1 authority for testing
fn create_swig_secp256r1(
    context: &mut SwigTestContext,
    public_key: &[u8; 33],
    id: [u8; 32],
) -> Result<(solana_sdk::pubkey::Pubkey, u8), Box<dyn std::error::Error>> {
    // To use find program address to get the swig address and bump

    // The instruction specifies the AuthorityType and the public key
    let create_ix = swig_interface::CreateInstruction::new(
        swig_address,
        swig_bump,
        payer_pubkey,
        AuthorityConfig {
            authority_type: AuthorityType::Secp256r1,
            authority: public_key,
        },
        vec![ClientAction::All(All {})], // Granting full permissions
        id,
    )?;

    // To create instruction using swig_interface::CreateInstruction
    // To create message using v0::Message::try_compile
    // To send transaction using context.svm.send_transaction

    Ok((swig_address, swig_bump))
}
```

A new **secp256r1** authority can be added to an existing account. This operation must be signed by a current authority. The test **test\_secp256r1\_add\_authority\_with\_secp256r1** demonstrates a **secp256r1** key authorizing the addition of another **secp256r1** key.

```rust theme={null}
#[test_log::test]
fn test_secp256r1_add_authority_with_secp256r1() {
    // Setup test context

    // The primary authority is secp256r1
    let (signing_key, public_key) = create_test_secp256r1_keypair();
    let (swig_key, _) = create_swig_secp256r1(&mut context, &public_key, id).unwrap();

    // The new authority to be added
    let (_, new_public_key) = create_test_secp256r1_keypair();

    // Get current slot and counter for the authority

    // Create the instruction to add the new authority.
    // This must be signed by the existing `public_key`.
    let instructions = swig_interface::AddAuthorityInstruction::new_with_secp256r1_authority(
        swig_key,
        context.default_payer.pubkey(),
        authority_fn,
        current_slot,
        next_counter,
        0, // role_id of the primary authority
        &public_key,
        AuthorityConfig {
            authority_type: AuthorityType::Secp256r1,
            authority: &new_public_key, // the new authority to be added
        },
        vec![ClientAction::All(All {})],
    )
    .unwrap();

    // To create instruction using swig_interface::CreateInstruction
    // To create message using v0::Message::try_compile
    // To send transaction using context.svm.send_transaction

    // Verify the authority was added
    let swig_account = context.svm.get_account(&swig_key).unwrap();
    let swig_state = SwigWithRoles::from_bytes(&swig_account.data).unwrap();
    assert_eq!(swig_state.state.roles, 2);

    // Verify the counter was incremented
    let new_counter = get_secp256r1_counter(&context, &swig_key, &public_key).unwrap();
    assert_eq!(
        new_counter, next_counter,
        "Counter should be incremented after successful transaction"
    );
}
```

#### C. Transaction Signing & Replay Protection:

Signing transactions with **secp256r1** is more complex than with **Ed25519**. It involves a critical feature for security: the **signature\_odometer**.

The **signature\_odometer:**

This is an on-chain counter (u32) that is part of the **Secp256r1Authority** struct.

A **get\_secp256r1\_counter** helper function reads this value from the swig account's data.

```rust theme={null}
/// Standard Secp256r1 authority implementation for passkey support.
///
/// This struct represents a Secp256r1 authority with a compressed public key
/// for signature verification using the Solana secp256r1 precompile program.
#[derive(Debug, no_padding::NoPadding)]
#[repr(C, align(8))]
pub struct Secp256r1Authority {
    /// The compressed Secp256r1 public key (33 bytes)
    pub public_key: [u8; 33],
    /// Padding for u32 alignment
    _padding: [u8; 3],
    /// Signature counter to prevent signature replay attacks
    pub signature_odometer: u32,
}
```

The **test\_secp256r1\_basic\_signing** test provides a perfect, low-level example of the signing flow.

```rust theme={null}
#[test_log::test]
fn test_secp256r1_basic_signing() {
    // Create a real secp256r1 key pair for testing

    // Create a new swig with the secp256r1 authority

    // Set up a recipient and transaction
    let transfer_ix = system_instruction::transfer(&swig_key, &recipient.pubkey(), transfer_amount);

    // Get the current on-chain counter
    let current_counter = get_secp256r1_counter(&context, &swig_key, &public_key).unwrap();
    let next_counter = current_counter + 1;

    // Create authority function that signs the message hash
    let mut authority_fn = |message_hash: &[u8]| -> [u8; 64] {
        use solana_secp256r1_program::sign_message;
        let signature =
            sign_message(message_hash, &signing_key.private_key_to_der().unwrap()).unwrap();
        signature
    };

    // Create the secp256r1 signing instructions (returns Vec<Instruction>)
    let instructions = swig_interface::SignInstruction::new_secp256r1(
        swig_key,
        context.default_payer.pubkey(),
        authority_fn,
        current_slot,
        next_counter,        // Provide the next expected counter
        transfer_ix.clone(), // The instruction to execute
        0,                   // The role ID of the secp256r1 key
        &public_key,
    )
    .unwrap();

    // Build and send the transaction
    let message = v0::Message::try_compile(
        &context.default_payer.pubkey(),
        &instructions, // These instructions include the secp256r1 program calls
        &[],
        context.svm.latest_blockhash(),
    )
    .unwrap();

    let tx =
        VersionedTransaction::try_new(VersionedMessage::V0(message), &[&context.default_payer])
            .unwrap();
    context.svm.send_transaction(tx).unwrap();

    // Verify the odometer was incremented on-chain
    let new_counter = get_secp256r1_counter(&context, &swig_key, &public_key).unwrap();
    assert_eq!(new_counter, next_counter);
}
```

#### D. Session Authorities:

SWIG also supports session-based **secp256r1** authorities. These are temporary keys with a defined lifespan, measured in Solana slots.

```rust theme={null}
/// Creation parameters for a session-based Secp256r1 authority.
#[derive(Debug, no_padding::NoPadding)]
#[repr(C, align(8))]
pub struct CreateSecp256r1SessionAuthority {
    /// The compressed Secp256r1 public key (33 bytes)
    pub public_key: [u8; 33],
    /// Padding for alignment
    _padding: [u8; 7],
    /// The session key for temporary authentication
    pub session_key: [u8; 32],
    /// Maximum duration a session can be valid for
    pub max_session_length: u64,
}

/// The `test_secp256r1_session_authority_odometer` test verifies that a session authority is
/// correctly initialized on-chain with its odometer set to 0.
#[test_log::test]
fn test_secp256r1_session_authority_odometer() {
    // setup

    // Create a swig with a session authority
    let (swig_key, _) =
        create_swig_secp256r1_session(&mut context, &public_key, id, 100, [0; 32]).unwrap();

    // get_session_counter helper to read the current odometer
    // Verify the initial counter is 0
    let initial_counter = get_session_counter(&context).unwrap();
    assert_eq!(initial_counter, 0, "Initial session counter should be 0");

    // Verify the authority type and session properties
    let swig_account = context.svm.get_account(&swig_key).unwrap();
    let swig = SwigWithRoles::from_bytes(&swig_account.data).unwrap();
    assert_eq!(swig.state.roles, 1);

    let role = swig.get_role(0).unwrap().unwrap();
    assert_eq!(
        role.authority.authority_type(),
        AuthorityType::Secp256r1Session
    );
    assert!(role.authority.session_based());

    let auth: &Secp256r1SessionAuthority = role.authority.as_any().downcast_ref().unwrap();
    assert_eq!(auth.max_session_age, 100);
    assert_eq!(auth.signature_odometer, 0, "Initial odometer should be 0");
}
```

## Live Examples

Explore these working implementations to see secp256r1 authorities in action:

<Card title="TypeScript secp256r1 Transfer" icon="code" href="https://github.com/anagrambuild/swig-ts/blob/main/examples/basic/classic/transfer-r1.ts">
  Complete TypeScript example demonstrating secp256r1 key generation, Swig creation, and transfer operations using LiteSVM
</Card>

<Card title="Passkey Helper Functions" icon="fingerprint" href="https://github.com/anagrambuild/swig-ts/blob/main/examples/secp-ui/src/helpers/passkey.ts">
  TypeScript helper functions for WebAuthn passkey integration with secp256r1 authorities
</Card>

<Card title="Interactive Passkey UI" icon="window" href="https://github.com/anagrambuild/swig-ts/tree/main/examples/secp-ui">
  Complete UI example showing how to build user-facing passkey authentication with secp256r1
</Card>

## Key Differences: TypeScript vs Rust

| Aspect                  | TypeScript                                         | Rust                                                     |
| ----------------------- | -------------------------------------------------- | -------------------------------------------------------- |
| **Key Generation**      | Uses `@noble/curves/nist` p256                     | Uses OpenSSL EcKey with X9\_62\_PRIME256V1               |
| **Public Key Format**   | Auto-compressed via `p256.getPublicKey(key, true)` | Manual compression via `PointConversionForm::COMPRESSED` |
| **Signing Function**    | `getSigningFnForSecp256r1PrivateKey()`             | Custom closure with `sign_message()`                     |
| **WebAuthn Support**    | Built-in passkey integration                       | Requires external WebAuthn library                       |
| **Testing Environment** | LiteSVM for lightweight testing                    | SwigTestContext with full SVM                            |
| **Use Cases**           | Client-side apps, browsers, passkeys               | Server-side, CLI tools, testing                          |

Both implementations provide the same cryptographic security and are fully compatible with the Swig protocol. Choose based on your deployment environment and integration needs.

```
```


# Working with Sessions in Swig
Source: https://build.onswig.com/examples/sessions

\"You can fit so many sessions in this bad boy\" - Toly slapping the hood of a gently used 2012 Swig (probably)

This guide explains how to work with sessions in Swig, which allow you to create temporary authorities with limited permissions. Sessions are perfect for dApp integrations where you need to delegate authority for a specific duration.
You can find all example code in the [swig-ts/examples/basic/classic](https://github.com/anagrambuild/swig-ts/tree/main/examples/basic/classic) directory.

<Tip>Examples with svm in the file name use LiteSVM for testing. Those without svm in the file name use a local validator. Which you can run with the `bun start-validator` command.</Tip>

## Creating a Basic Session

The simplest way to create a session is with Ed25519 keys. Here are the key parts:

<Tabs>
  <Tab title="Classic">
    ```typescript theme={null}
    import {
      Connection,
      Keypair,
      LAMPORTS_PER_SOL,
    } from '@solana/web3.js';
    import {
      Actions,
      createEd25519SessionAuthorityInfo,
      findSwigPda,
      getCreateSwigInstruction,
      getCreateSessionInstructions,
    } from '@swig-wallet/classic';

    // Setup - Create root authority and session keypair
    const userRootKeypair = Keypair.generate();
    const dappSessionKeypair = Keypair.generate();

    const connection = new Connection('http://localhost:8899', 'confirmed');

    // Create Swig with session support
    const id = randomBytes(32);
    const swigAccountAddress = findSwigPda(id);
    const rootActions = Actions.set().all().get();

    const ix = await getCreateSwigInstruction({
      id,
      authorityInfo: createEd25519SessionAuthorityInfo(
        userRootKeypair.publicKey,
        100n,
      ),
      actions: rootActions,
      payer: userRootKeypair.publicKey,
    });

    // Create a session that lasts 50 slots
    const createSessionIx = await getCreateSessionInstructions(
      swig,
      rootRole.id,
      dappSessionKeypair.publicKey,
      50n,
    );
    // Create a session that lasts 50 slots
    const createSessionIx = await getCreateSessionInstructions(
      swig,
      rootRole.id,
      dappSessionKeypair.publicKey,
      50n,
    );
    ```
  </Tab>

  <Tab title="Kit">
    ```typescript theme={null}
    import {
      createSolanaRpc,
      createSolanaRpcSubscriptions,
      generateKeyPairSigner,
      lamports,
    } from '@solana/kit';
    import {
      Actions,
      createEd25519SessionAuthorityInfo,
      findSwigPda,
      getCreateSwigInstruction,
      getCreateSessionInstructions,
    } from '@swig-wallet/kit';

    // Setup - Create root authority and session keypair
    const userRootKeypair = await generateKeyPairSigner();
    const dappSessionKeypair = await generateKeyPairSigner();

    const connection = {
      rpc: createSolanaRpc('http://localhost:8899'),
      rpcSubscriptions: createSolanaRpcSubscriptions('ws://localhost:8900'),
    };

    // Create Swig with session support
    const id = randomBytes(32);
    const swigAccountAddress = await findSwigPda(id);
    const rootActions = Actions.set().all().get();

    const createSwigIx = await getCreateSwigInstruction({
      id,
      authorityInfo: createEd25519SessionAuthorityInfo(userRootKeypair.address, 100n),
      actions: rootActions,
      payer: userRootKeypair.address,
    });

    // Create a session that lasts 50 slots
    const createSessionIx = await getCreateSessionInstructions(
      swig,
      rootRole.id,
      dappSessionKeypair.address,
      50n,
    );
    ```
  </Tab>
</Tabs>

## Using Session Authority

Once a session is created, you can use it to sign transactions within its duration:

<Tabs>
  <Tab title="Classic">
    ```typescript theme={null}
    import {
      SystemProgram,
      LAMPORTS_PER_SOL,
    } from '@solana/web3.js';
    import {
      fetchSwig,
      getSignInstructions,
      getSwigWalletAddress,
    } from '@swig-wallet/classic';

    // Find the role by session key
    const swig = await fetchSwig(connection, swigAccountAddress);
    const swigWalletAddress = await getSwigWalletAddress(swig);
    const rootRole = swig.findRoleBySessionKey(dappSessionKeypair.publicKey);

    if (!rootRole || !rootRole.isSessionBased())
      throw new Error('Role not found for authority');

    // Create and sign a transfer using session authority (use swigWalletAddress)
    const transfer = SystemProgram.transfer({
      fromPubkey: swigWalletAddress,
      toPubkey: dappTreasury,
      lamports: 0.1 * LAMPORTS_PER_SOL,
    });

    const signTransfer = await getSignInstructions(
      swig,
      rootRole.id,
      [transfer],
      false,
      { payer: dappSessionKeypair.publicKey },
    );

    await sendTransaction(connection, signTransfer, dappSessionKeypair);
    ```
  </Tab>

  <Tab title="Kit">
    ```typescript theme={null}
    import {
      getTransferSolInstructionDataEncoder,
      SYSTEM_PROGRAM_ADDRESS,
    } from '@solana-program/system';
    import {
      AccountRole,
      type IInstruction,
    } from '@solana/kit';
    import {
      fetchSwig,
      getSignInstructions,
      getSwigWalletAddress,
    } from '@swig-wallet/kit';

    // Find the role by session key
    const swig = await fetchSwig(connection.rpc, swigAccountAddress);
    const swigWalletAddress = await getSwigWalletAddress(swig);
    const sessionRole = swig.findRolesByEd25519SignerPk(dappSessionKeypair.address)[0];

    if (!sessionRole || !sessionRole.isSessionBased())
      throw new Error('Role not found for authority');

    // Create and sign a transfer using session authority (use swigWalletAddress)
    const transferIx: IInstruction = {
      programAddress: SYSTEM_PROGRAM_ADDRESS,
      accounts: [
        { address: swigWalletAddress, role: AccountRole.WRITABLE_SIGNER },
        { address: dappTreasury.address, role: AccountRole.WRITABLE },
      ],
      data: new Uint8Array(
        getTransferSolInstructionDataEncoder().encode({
          amount: BigInt(0.1 * LAMPORTS_PER_SOL),
        })
      ),
    };

    const signTransfer = await getSignInstructions(
      swig,
      sessionRole.id,
      [transferIx],
      false,
      { payer: dappSessionKeypair.address },
    );

    await sendTransaction(connection, signTransfer, dappSessionKeypair);
    ```
  </Tab>
</Tabs>

## Secp256k1 Sessions (EVM Compatible)

For EVM compatibility, you can create sessions with Secp256k1 keys:

<Tabs>
  <Tab title="Classic">
    ```typescript theme={null}
    import { Wallet } from '@ethereumjs/wallet';
    import {
      createSecp256k1SessionAuthorityInfo,
      getSigningFnForSecp256k1PrivateKey,
      getCreateSwigInstruction,
      getCreateSessionInstructions,
    } from '@swig-wallet/classic';

    // Setup with Ethereum wallet
    const userWallet = Wallet.generate();

    // Create Swig with Secp256k1 session support
    const createSwigInstruction = await getCreateSwigInstruction({
      authorityInfo: createSecp256k1SessionAuthorityInfo(
        userWallet.getPublicKey(),
        100n,
      ),
      id,
      payer: userRootKeypair.publicKey,
      actions: rootActions,
    });

    // Create a session
    const currentSlot = await connection.getSlot('confirmed');
    const signingFn = getSigningFnForSecp256k1PrivateKey(
      userWallet.getPrivateKeyString(),
    );

    const sessionInstructions = await getCreateSessionInstructions(
      swig,
      rootRole.id,
      dappSessionKeypair.publicKey,
      50n,
      { 
        payer: userRootKeypair.publicKey,
        currentSlot: BigInt(currentSlot),
        signingFn,
      },
    );
    ```
  </Tab>

  <Tab title="Kit">
    ```typescript theme={null}
    import { Wallet } from '@ethereumjs/wallet';
    import {
      createSecp256k1SessionAuthorityInfo,
      getSigningFnForSecp256k1PrivateKey,
      getCreateSwigInstruction,
      getCreateSessionInstructions,
    } from '@swig-wallet/kit';

    // Setup with Ethereum wallet
    const userWallet = Wallet.generate();

    // Create Swig with Secp256k1 session support
    const authorityInfo = createSecp256k1SessionAuthorityInfo(
      userWallet.getPublicKey(),
      100n, // Max session duration
    );

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

    // Create a session
    const currentSlot = await connection.rpc.getSlot().send();
    const signingFn = getSigningFnForSecp256k1PrivateKey(userWallet.getPrivateKey());

    const sessionInstructions = await getCreateSessionInstructions(
      swig,
      rootRole.id,
      dappSessionKeypair.address,
      50n, // Session duration in slots
      { 
        payer: userRootKeypair.address,
        currentSlot,
        signingFn,
      },
    );
    ```
  </Tab>
</Tabs>

## Revoking Sessions

You can revoke a session by creating a new session with an all-zero session key:

<Tabs>
  <Tab title="Classic">
    ```typescript theme={null}
    import { getCreateSessionInstructions } from '@swig-wallet/classic';

    // Create a zero key to revoke the session
    const zeroKey = new Uint8Array(32).fill(0);

    // Create revocation instruction
    const revokeSessionIx = await getCreateSessionInstructions(
      swig,
      rootRole.id,
      zeroKey,
      1n, // Duration doesn't matter for revocation
    );

    await sendTransaction(connection, revokeSessionIx, userRootKeypair);
    ```
  </Tab>

  <Tab title="Kit">
    ```typescript theme={null}
    import { getCreateSessionInstructions } from '@swig-wallet/kit';

    // Create a zero key to revoke the session
    const zeroKey = new Uint8Array(32).fill(0);

    // Create revocation instruction
    const revokeSessionIx = await getCreateSessionInstructions(
      swig,
      rootRole.id,
      zeroKey,
      1n, // Duration doesn't matter for revocation
    );

    await sendTransaction(connection, revokeSessionIx, userRootKeypair);
    ```
  </Tab>
</Tabs>

## Key Aspects of Sessions

Sessions in Swig have several important characteristics:

* **Temporary Authority**: Sessions expire after their specified duration
* **Unique Keys**: Each session must use a unique key (can't reuse previous session keys)
* **Root Override**: The root authority can always override or revoke session permissions
* **Inheritance**: Sessions inherit permissions from their root role
* **Multiple Sessions**: You can have multiple active sessions for the same root authority

## Testing Environment Options

These examples can be run in different environments:

* **Local Validator**: Use the examples with 'local' in the filename
  * Requires running a local Solana validator with `bun start-validator`
  * Real blockchain environment
  * Good for final testing

* **LiteSVM**: Use examples with `svm` in the filename
  * No validator required
  * Instant transaction confirmation
  * Perfect for rapid development
  * Simulates the Solana runtime

* **Devnet**: All examples work with devnet
  * Change connection URL to `https://api.devnet.solana.com`
  * Real network environment
  * Free to use with airdropped SOL

<Tabs>
  <Tab title="Classic">
    ```typescript theme={null}
    // Local validator
    const connection = new Connection('http://localhost:8899', 'confirmed');

    // Devnet
    const connection = new Connection('https://api.devnet.solana.com', 'confirmed');
    ```
  </Tab>

  <Tab title="Kit">
    ```typescript theme={null}
    // Local validator
    const connection = {
      rpc: createSolanaRpc('http://localhost:8899'),
      rpcSubscriptions: createSolanaRpcSubscriptions('ws://localhost:8900'),
    };

    // Devnet
    const connection = {
      rpc: createSolanaRpc('https://api.devnet.solana.com'),
      rpcSubscriptions: createSolanaRpcSubscriptions('wss://api.devnet.solana.com'),
    };
    ```
  </Tab>
</Tabs>

LiteSVM is recommended for initial development as it provides the fastest feedback loop. Move to local validator or devnet for more thorough testing.


# Sub Accounts in Swig
Source: https://build.onswig.com/examples/sub_accounts

\"Its sub accounts all the way down\" - Ancient Swig Proverb

This guide explains how to work with sub accounts in Swig, which allow authorities to create and manage dedicated sub account addresses with specific permissions. Sub accounts are perfect for use cases like portfolio management where you want to delegate complex operations without giving control over all assets.

You can find complete working examples in the Swig repository:

* [Classic Example](https://github.com/anagrambuild/swig-ts/blob/main/examples/basic/classic/transfer-subaccount.ts)
* [Kit Example](https://github.com/anagrambuild/swig-ts/blob/main/examples/basic/kit/transfer-subaccount.ts)

## What are Sub Accounts?

Sub accounts in Swig allow an authority to create and manage a single sub account address and perform any actions on behalf of that sub account. This is a super high level of permission so use with care. It works for use cases like portfolio management, where you want to allow an unlimited complexity of actions on behalf of a single address, but you don't want to give the authority control over all the assets of the swig. The root authority can always pull funds (SOL and tokens) from the sub account back to the main Swig wallet.

A great example of this is Breeze, Anagram's onchain yield optimizer. Breeze can optimize the yield of a user's portfolio without giving them control over their whole swig.

## How Sub Accounts Work

To work with sub accounts, there are several key steps:

1. **Sub Account Permission**: The authority must have the sub account permission to create the sub account. This permission is set when creating or modifying a role.
2. **Create Sub Account**: Once the authority has the permission, they can create a sub account using the `getCreateSubAccountInstructions`.
3. **Sub Account Sign**: Once created, sub accounts can perform on-chain actions using the `getSignInstructions` with the `isSubAccount` parameter set to `true`.

<Warning>
  **Critical Requirement**: Creating a subaccount requires a **two-step process**:

  1. **First**: Add a `SubAccount` permission to a new or existing Authority on your Swig wallet
  2. **Second**: Create the actual subaccount, which populates the blank SubAccount action with the subaccount's public key

  **Important**: Even if an authority has `All` permission, you **must** explicitly add the `SubAccount` permission with a blank subaccount (`[0; 32]` in Rust, or using `Actions.set().subAccount().get()` in TypeScript) to enable subaccount creation. The `All` permission alone is not sufficient for subaccount creation.
</Warning>

## Creating a Sub Account Authority

First, you need to add an authority with sub account permissions:

<Tabs>
  <Tab title="Classic">
    ```typescript theme={null}
    import {
      Keypair,
      LAMPORTS_PER_SOL,
    } from '@solana/web3.js';
    import {
      Actions,
      createEd25519AuthorityInfo,
      findSwigPda,
      getAddAuthorityInstructions,
      getCreateSwigInstruction,
      fetchSwig,
    } from '@swig-wallet/classic';

    // Create authorities
    const rootAuthority = Keypair.generate();
    const subAccountAuthority = Keypair.generate();

    // Create Swig with root authority
    const id = Uint8Array.from(Array(32).fill(2));
    const swigAddress = findSwigPda(id);

    const createSwigIx = await getCreateSwigInstruction({
      payer: rootAuthority.publicKey,
      actions: Actions.set().all().get(),
      authorityInfo: createEd25519AuthorityInfo(rootAuthority.publicKey),
      id,
    });

    // Add sub account authority with sub account permissions
    const swig = await fetchSwig(connection, swigAddress);
    const rootRole = swig.roles[0];

    const addAuthorityIx = await getAddAuthorityInstructions(
      swig,
      rootRole.id,
      createEd25519AuthorityInfo(subAccountAuthority.publicKey),
      Actions.set().subAccount().get(),
    );
    ```
  </Tab>

  <Tab title="Kit">
    ```typescript theme={null}
    import {
      generateKeyPairSigner,
      lamports,
    } from '@solana/kit';
    import {
      Actions,
      createEd25519AuthorityInfo,
      findSwigPda,
      getAddAuthorityInstructions,
      getCreateSwigInstruction,
      fetchSwig,
    } from '@swig-wallet/kit';

    // Create authorities
    const rootAuthority = await generateKeyPairSigner();
    const subAccountAuthority = await generateKeyPairSigner();

    // Create Swig with root authority
    const id = randomBytes(32);
    const swigAddress = await findSwigPda(id);

    const createSwigIx = await getCreateSwigInstruction({
      payer: rootAuthority.address,
      actions: Actions.set().all().get(),
      authorityInfo: createEd25519AuthorityInfo(rootAuthority.address),
      id,
    });

    // Add sub account authority with sub account permissions
    const swig = await fetchSwig(connection.rpc, swigAddress);
    const rootRole = swig.roles[0];

    const addAuthorityIx = await getAddAuthorityInstructions(
      swig,
      rootRole.id,
      createEd25519AuthorityInfo(subAccountAuthority.address),
      Actions.set().subAccount().get(),
    );
    ```
  </Tab>

  <Tab title="Rust">
    ```rust theme={null}
    use solana_program::pubkey::Pubkey;
    use solana_sdk::{
        message::{v0, VersionedMessage},
        signature::Keypair,
        transaction::VersionedTransaction,
    };
    use swig_sdk::{
        SwigInstructionBuilder,
        client_role::Ed25519ClientRole,
        types::Permission,
        AuthorityType,
    };

    // Create keypairs for authorities
    let root_authority = Keypair::new();
    let sub_account_authority = Keypair::new();
    let fee_payer = Keypair::new();

    // Generate a unique Swig wallet ID
    let swig_id = rand::random::<[u8; 32]>();

    // Step 1: Create the Swig account with root authority
    let mut root_builder = SwigInstructionBuilder::new(
        swig_id,
        Box::new(Ed25519ClientRole::new(root_authority.pubkey())),
        fee_payer.pubkey(),
        0, // root role_id
    );

    let create_swig_ix = root_builder.build_swig_account()?;

    // Send transaction to create Swig account
    // ... (compile message, sign, send transaction)

    // Step 2: Add a new authority with SubAccount permission
    // 
    // IMPORTANT: You must include the blank SubAccount permission even if
    // you're also granting All permission. The blank SubAccount action
    // (with sub_account: [0; 32]) is required and will be populated when
    // the subaccount is created.
    let add_authority_ix = root_builder.add_authority_instruction(
        AuthorityType::Ed25519,
        &sub_account_authority.pubkey().to_bytes(),
        vec![
            Permission::SubAccount {
                sub_account: [0; 32], // Blank subaccount - will be populated on creation
            },
        ],
        None, // current_slot not required for Ed25519
    )?;

    // If you want to grant All permission AND SubAccount permission:
    let add_authority_with_all_ix = root_builder.add_authority_instruction(
        AuthorityType::Ed25519,
        &sub_account_authority.pubkey().to_bytes(),
        vec![
            Permission::All,
            Permission::SubAccount {
                sub_account: [0; 32], // Blank subaccount - REQUIRED even with All
            },
        ],
        None,
    )?;

    // Send transaction to add authority
    // ... (compile message, sign with root_authority, send transaction)
    ```
  </Tab>
</Tabs>

## Creating a Sub Account

Once you have an authority with sub account permissions, you can create the sub account:

<Tabs>
  <Tab title="Classic">
    ```typescript theme={null}
    import {
      findSwigSubAccountPda,
      getCreateSubAccountInstructions,
    } from '@swig-wallet/classic';

    // Refetch swig to get updated roles
    await swig.refetch();
    const subAccountAuthRole = swig.roles[1];

    // Create sub account
    const createSubAccountIx = await getCreateSubAccountInstructions(
      swig,
      subAccountAuthRole.id,
    );

    await sendTransaction(connection, createSubAccountIx, subAccountAuthority);

    // Get the sub account address
    const subAccountAddress = findSwigSubAccountPda(
      subAccountAuthRole.swigId,
      subAccountAuthRole.id,
    );
    ```
  </Tab>

  <Tab title="Kit">
    ```typescript theme={null}
    import {
      findSwigSubAccountPda,
      getCreateSubAccountInstructions,
    } from '@swig-wallet/kit';

    // Refetch swig to get updated roles
    await swig.refetch();
    const subAccountAuthRole = swig.roles[1];

    // Create sub account
    const createSubAccountIx = await getCreateSubAccountInstructions(
      swig,
      subAccountAuthRole.id,
    );

    await sendTransaction(connection, createSubAccountIx, subAccountAuthority);

    // Get the sub account address
    const subAccountAddress = await findSwigSubAccountPda(
      subAccountAuthRole.swigId,
      subAccountAuthRole.id,
    );
    ```
  </Tab>

  <Tab title="Rust">
    ```rust theme={null}
    use solana_program::pubkey::Pubkey;
    use solana_sdk::{
        message::{v0, VersionedMessage},
        signature::Keypair,
        transaction::VersionedTransaction,
    };
    use swig_sdk::{
        SwigInstructionBuilder,
        client_role::Ed25519ClientRole,
    };
    use swig_state::swig::sub_account_seeds;
    use swig_interface::program_id;

    // Step 1: Get the role ID of the newly added authority
    // In production, you would fetch the Swig account and look up the role ID
    // For this example, we know it will be role_id 1 (first added authority)
    let sub_account_role_id = 1;

    // Step 2: Create the subaccount using the sub-account authority
    let mut sub_account_builder = SwigInstructionBuilder::new(
        swig_id,
        Box::new(Ed25519ClientRole::new(sub_account_authority.pubkey())),
        fee_payer.pubkey(),
        sub_account_role_id,
    );

    let create_sub_account_ix = sub_account_builder.create_sub_account(None)?;

    // Send transaction to create subaccount
    let recent_blockhash = rpc_client.get_latest_blockhash()?;
    let msg = v0::Message::try_compile(
        &fee_payer.pubkey(),
        &[create_sub_account_ix],
        &[],
        recent_blockhash,
    )?;

    let tx = VersionedTransaction::try_new(
        VersionedMessage::V0(msg),
        &[fee_payer, &sub_account_authority],
    )?;

    rpc_client.send_and_confirm_transaction(&tx)?;

    // Step 3: Derive the subaccount address to verify it was created
    let role_id_bytes = sub_account_role_id.to_le_bytes();
    let (sub_account, _bump) = Pubkey::find_program_address(
        &sub_account_seeds(&swig_id, &role_id_bytes),
        &program_id(),
    );

    println!("Subaccount created at: {}", sub_account);
    ```
  </Tab>
</Tabs>

## Creating Swig Account and SubAccount in One Transaction

If you're creating a new Swig wallet and want to set up a subaccount immediately, you can create both the Swig account with subaccount authority and the subaccount itself in a single transaction. This reduces the number of transactions needed from 3 to 1.

<Tabs>
  <Tab title="Rust">
    ```rust theme={null}
    use solana_program::pubkey::Pubkey;
    use solana_sdk::{
        message::{v0, VersionedMessage},
        signature::Keypair,
        transaction::VersionedTransaction,
    };
    use swig_interface::{
        AuthorityConfig, ClientAction, CreateInstruction, CreateSubAccountInstruction,
    };
    use swig_state::{
        action::{all::All, sub_account::SubAccount},
        authority::AuthorityType,
        swig::{sub_account_seeds, swig_account_seeds, swig_wallet_address_seeds},
    };

    fn create_swig_and_subaccount_in_one_tx(
        rpc_client: &RpcClient,
        authority: &Keypair,
        fee_payer: &Keypair,
    ) -> Result<(Pubkey, Pubkey), Box<dyn std::error::Error>> {
        let swig_id = rand::random::<[u8; 32]>();
        let program_id = swig_interface::program_id();

        // Derive the Swig account address
        let (swig_key, swig_bump) =
            Pubkey::find_program_address(&swig_account_seeds(&swig_id), &program_id);
        let (swig_wallet_address, wallet_address_bump) = Pubkey::find_program_address(
            &swig_wallet_address_seeds(swig_key.as_ref()),
            &program_id,
        );

        // Derive the sub-account address (role_id 0 since this is the initial authority)
        let role_id: u32 = 0;
        let role_id_bytes = role_id.to_le_bytes();
        let (sub_account, sub_account_bump) =
            Pubkey::find_program_address(&sub_account_seeds(&swig_id, &role_id_bytes), &program_id);

        // Step 1: Create instruction to create Swig account with All + SubAccount permissions
        let create_swig_ix = CreateInstruction::new(
            swig_key,
            swig_bump,
            fee_payer.pubkey(),
            swig_wallet_address,
            wallet_address_bump,
            AuthorityConfig {
                authority_type: AuthorityType::Ed25519,
                authority: authority.pubkey().as_ref(),
            },
            vec![
                ClientAction::All(All {}),
                ClientAction::SubAccount(SubAccount::new_for_creation()),
            ],
            swig_id,
        )?;

        // Step 2: Create instruction to create the subaccount
        // This uses role_id 0 since the authority is the initial/root authority
        let create_sub_account_ix = CreateSubAccountInstruction::new_with_ed25519_authority(
            swig_key,
            authority.pubkey(),
            fee_payer.pubkey(),
            sub_account,
            role_id,
            sub_account_bump,
        )?;

        // Step 3: Submit both instructions in a single transaction
        let recent_blockhash = rpc_client.get_latest_blockhash()?;
        let message = v0::Message::try_compile(
            &fee_payer.pubkey(),
            &[create_swig_ix, create_sub_account_ix],
            &[],
            recent_blockhash,
        )?;

        let tx = VersionedTransaction::try_new(
            VersionedMessage::V0(message),
            &[fee_payer, authority],
        )?;

        rpc_client.send_and_confirm_transaction(&tx)?;

        // Verify both accounts were created
        let swig_account = rpc_client.get_account(&swig_key)?;
        let sub_account_data = rpc_client.get_account(&sub_account)?;
        
        assert_eq!(sub_account_data.owner, solana_sdk::system_program::id());

        Ok((swig_key, sub_account))
    }
    ```
  </Tab>
</Tabs>

**Note**: This approach attempts to create both the Swig account and subaccount atomically in a single transaction. While this can be more efficient, it may fail if the subaccount creation instruction requires the Swig account to be fully initialized and written to the blockchain first. If this fails, fall back to the multi-transaction approach shown in the previous examples.

## Using Sub Accounts

Once created, you can use the sub account to perform transactions:

<Tabs>
  <Tab title="Classic">
    ```typescript theme={null}
    import {
      SystemProgram,
      LAMPORTS_PER_SOL,
    } from '@solana/web3.js';
    import {
      getSignInstructions,
    } from '@swig-wallet/classic';

    // Fund the sub account
    await connection.requestAirdrop(subAccountAddress, LAMPORTS_PER_SOL);

    // Create a transfer from the sub account
    const recipient = Keypair.generate().publicKey;

    const transfer = SystemProgram.transfer({
      fromPubkey: subAccountAddress,
      toPubkey: recipient,
      lamports: 0.1 * LAMPORTS_PER_SOL,
    });

    // Sign with sub account (note: isSubAccount = true)
    const signIx = await getSignInstructions(
      swig,
      subAccountAuthRole.id,
      [transfer],
      true, // isSubAccount flag
    );

    await sendTransaction(connection, signIx, subAccountAuthority);
    ```
  </Tab>

  <Tab title="Kit">
    ```typescript theme={null}
    import {
      getTransferSolInstructionDataEncoder,
      SYSTEM_PROGRAM_ADDRESS,
    } from '@solana-program/system';
    import {
      AccountRole,
      generateKeyPairSigner,
      lamports,
    } from '@solana/kit';
    import {
      getSignInstructions,
    } from '@swig-wallet/kit';

    // Fund the sub account
    await connection.rpc
      .requestAirdrop(subAccountAddress, lamports(BigInt(LAMPORTS_PER_SOL)))
      .send();

    // Create a transfer from the sub account
    const recipient = (await generateKeyPairSigner()).address;

    const transfer = {
      programAddress: SYSTEM_PROGRAM_ADDRESS,
      accounts: [
        {
          address: subAccountAddress,
          role: AccountRole.WRITABLE_SIGNER,
        },
        {
          address: recipient,
          role: AccountRole.WRITABLE,
        },
      ],
      data: new Uint8Array(
        getTransferSolInstructionDataEncoder().encode({
          amount: 0.1 * LAMPORTS_PER_SOL,
        }),
      ),
    };

    // Sign with sub account (note: isSubAccount = true)
    const signIx = await getSignInstructions(
      swig,
      subAccountAuthRole.id,
      [transfer],
      true, // isSubAccount flag
    );

    await sendTransaction(connection, signIx, subAccountAuthority);
    ```
  </Tab>

  <Tab title="Rust">
    ```rust theme={null}
    use solana_program::{
        instruction::Instruction,
        pubkey::Pubkey,
        system_instruction,
    };
    use solana_sdk::{
        message::{v0, VersionedMessage},
        signature::Keypair,
        transaction::VersionedTransaction,
    };
    use swig_sdk::{
        SwigInstructionBuilder,
        client_role::Ed25519ClientRole,
    };

    // Fund the sub account
    rpc_client.request_airdrop(&sub_account, 1_000_000_000)?; // 1 SOL

    // Create a transfer from the sub account
    let recipient = Keypair::new().pubkey();
    let transfer_amount = 100_000_000; // 0.1 SOL

    // Create the transfer instruction targeting the subaccount
    // The subaccount address is used as the 'from' account
    let transfer_ix = system_instruction::transfer(
        &sub_account,      // from: subaccount address
        &recipient,        // to: recipient
        transfer_amount,   // amount
    );

    // Sign with sub account using the SwigInstructionBuilder
    // Note: The builder should be configured with the sub_account_authority
    // and the appropriate role_id that has subaccount permissions
    let mut sub_account_builder = SwigInstructionBuilder::new(
        swig_id,
        Box::new(Ed25519ClientRole::new(sub_account_authority.pubkey())),
        fee_payer.pubkey(),
        sub_account_role_id,
    );

    // Sign the instruction for subaccount use
    // The sign_instruction method will handle subaccount signing when the role
    // has subaccount permissions and the instruction targets the subaccount address
    let signed_instructions = sub_account_builder.sign_instruction(
        vec![transfer_ix],
        None, // current_slot not required for Ed25519
    )?;

    // Build and send the transaction
    let recent_blockhash = rpc_client.get_latest_blockhash()?;
    let msg = v0::Message::try_compile(
        &fee_payer.pubkey(),
        &signed_instructions,
        &[],
        recent_blockhash,
    )?;

    let tx = VersionedTransaction::try_new(
        VersionedMessage::V0(msg),
        &[fee_payer, &sub_account_authority],
    )?;

    rpc_client.send_and_confirm_transaction(&tx)?;
    ```
  </Tab>
</Tabs>

## Key Features of Sub Accounts

Sub accounts in Swig have several important characteristics:

* **Dedicated Address**: Each sub account has its own unique address derived from the Swig ID and role ID
* **Isolated Operations**: Sub accounts can perform complex operations without affecting the main Swig balance
* **Root Authority Control**: The root authority can always reclaim funds from sub accounts
* **Permission-Based**: Only authorities with sub account permissions can create and manage sub accounts
* **Unlimited Actions**: Sub accounts can perform any on-chain action within their permission scope

## Testing Environment Options

These examples can be run in different environments:

* **Local Validator**: Use the examples above
  * Requires running a local Solana validator with `bun start-validator`
  * Real blockchain environment
  * Good for final testing

* **LiteSVM**: For rapid development and testing
  * No validator required
  * Instant transaction confirmation
  * Perfect for rapid development
  * Simulates the Solana runtime

* **Devnet**: All examples work with devnet
  * Change connection URL to `https://api.devnet.solana.com`
  * Real network environment
  * Free to use with airdropped SOL

<Tabs>
  <Tab title="Classic">
    ```typescript theme={null}
    // Local validator
    const connection = new Connection('http://localhost:8899', 'confirmed');

    // Devnet
    const connection = new Connection('https://api.devnet.solana.com', 'confirmed');
    ```
  </Tab>

  <Tab title="Kit">
    ```typescript theme={null}
    // Local validator
    const connection = {
      rpc: createSolanaRpc('http://localhost:8899'),
      rpcSubscriptions: createSolanaRpcSubscriptions('ws://localhost:8900'),
    };

    // Devnet
    const connection = {
      rpc: createSolanaRpc('https://api.devnet.solana.com'),
      rpcSubscriptions: createSolanaRpcSubscriptions('wss://api.devnet.solana.com'),
    };
    ```
  </Tab>
</Tabs>

## Use Cases

Sub accounts are perfect for:

* **Portfolio Management**: Allow complex DeFi operations without full wallet access
* **Yield Optimization**: Automated strategies with isolated risk
* **Multi-Strategy Trading**: Separate accounts for different trading strategies
* **Delegation**: Give specific permissions for particular use cases

## Additional Resources

You can find more working examples in our repositories:

* **Rust Examples**: [Swig test suite](https://github.com/anagrambuild/swig-wallet/blob/main/program/tests/sub_account_test.rs#L33)
* **Classic TypeScript**: [transfer-subaccount.ts](https://github.com/anagrambuild/swig-ts/blob/main/examples/basic/classic/transfer-subaccount.ts)
* **Kit TypeScript**: [transfer-subaccount.ts](https://github.com/anagrambuild/swig-ts/blob/main/examples/basic/kit/transfer-subaccount.ts)
* **All Examples**: [Swig TypeScript examples](https://github.com/anagrambuild/swig-ts/tree/main/examples)


# Subscriptions with Swig
Source: https://build.onswig.com/examples/subscription

"Please like and most importantly, subscribe" - Swig Content Influencers Everywhere

# Building Subscription Services with SWIG

SWIG's token limit feature provides a powerful way to implement subscription-based services on Solana. This guide demonstrates how to create a subscription service that charges users monthly using SWIG's token limit capabilities.

You can find the complete example code here:

* **Classic SDK**: [subscription.ts](https://github.com/anagrambuild/swig-ts/blob/main/examples/basic/classic/subscription.ts) (uses LiteSVM for testing)
* **Kit SDK**: [subscription.ts](https://github.com/anagrambuild/swig-ts/blob/main/examples/basic/kit/subscription.ts) (uses local validator)

<Tip>
  Examples with svm in the file name use LiteSVM for testing. Those without svm in the file name use a local validator. Which you can run with the bun start-validator command.
</Tip>

## Overview

In this example, we'll create a subscription service that:

* Charges users \$10 USDC monthly
* Uses SWIG's token limit feature to enforce the subscription amount and period
* Demonstrates how the limit resets after the specified period

## Key Concepts

### Token Limits

SWIG's token limit feature allows you to:

* Set a maximum amount of tokens that can be transferred within a specified block period
* Automatically reset the limit after the period expires
* Track limits per token mint (supporting multiple tokens)

### Block Period

In this example, we use a block period of 216,000 blocks, which approximates one month given Solana's average block time of 400ms:

```typescript theme={null}
// 400ms per block
// 1 month ≈ 30 days * 24 hours * 60 minutes * 60 seconds * (1/0.4) blocks/second
// ≈ 216,000 blocks
```

## Implementation

The example demonstrates:

1. Creating a SWIG wallet with root authority
2. Setting up a subscription service authority with token limits
3. Processing subscription paymentsI
4. Handling period resets

Here's a key snippet showing how to set up the subscription authority:

<Tabs>
  <Tab title="Classic">
    ```typescript theme={null}
    // Set subscription service authority with 0.1 SOL monthly limit
    // 400ms per block, so ~216000 blocks per month
    const subscriptionActions = Actions.set()
      .solRecurringLimit({
        recurringAmount: BigInt(0.1 * LAMPORTS_PER_SOL), // 0.1 SOL
        window: BigInt(216000),
      })
      .get();

    const addSubscriptionAuthorityIx = await getAddAuthorityInstructions(
      swig,
      rootRole.id,
      createEd25519AuthorityInfo(subscriptionServiceKeypair.publicKey),
      subscriptionActions,
      { payer: rootKeypair.publicKey },
    );
    ```
  </Tab>

  <Tab title="Kit">
    ```typescript theme={null}
    // Set subscription service authority with 0.1 SOL recurring limit
    const recurringActions = Actions.set()
      .solRecurringLimit({
        recurringAmount: BigInt(0.1 * LAMPORTS_PER_SOL),
        window: BigInt(20), // block-based window
      })
      .get();

    const addAuthorityIx = await getAddAuthorityInstructions(
      swig,
      rootRole.id,
      createEd25519AuthorityInfo(subscription.address),
      recurringActions,
    );
    ```
  </Tab>
</Tabs>

## Use Cases

This pattern enables various subscription-based services:

1. **SaaS Applications**
   * Monthly software subscriptions
   * Tiered service plans
   * Usage-based billing

2. **Content Platforms**
   * Premium content access
   * Streaming services
   * Digital publication subscriptions

3. **Gaming Services**
   * Monthly game passes
   * Premium features access
   * In-game subscription benefits

4. **DeFi Services**
   * Trading fee subscriptions
   * Premium analytics access
   * Automated trading services

## Complete Example

For a complete working example that includes both client and server implementations, check out the [SWIG SDK Example Repository](https://github.com/anagrambuild/swig-rs-sdk-example). This repository demonstrates:

* Frontend subscription management
* Backend subscription processing
* Error handling and edge cases
* User management integration

## Best Practices

1. **Error Handling**
   * Always verify transaction success
   * Handle failed payments gracefully
   * Implement retry mechanisms

2. **User Experience**
   * Notify users before renewal
   * Provide clear subscription status
   * Implement grace periods

3. **Security**
   * Secure key management
   * Rate limiting
   * Transaction monitoring


# Jupiter Swapping with Swig
Source: https://build.onswig.com/examples/swap

"To swap or not to swap, that is the question" - Swigspere

# Swapping Tokens with Jupiter using Swig

This guide demonstrates how to perform token swaps on Solana using Jupiter Protocol with a Swig wallet. We'll create a simple example that swaps SOL for USDC using Jupiter's optimized routing.

## Prerequisites

Before you begin, make sure you have the following installed:

* [Bun](https://bun.sh) (latest version)
* A Solana wallet with some SOL for transaction fees (at least 0.02 SOL)
* A keypair file for the root user
* RPC\_URL environment variable set to your Solana RPC endpoint

## Setup

First, clone the swig-ts repository and navigate to the swap example:

```bash theme={null}
git clone https://github.com/anagrambuild/swig-ts.git
cd swig-ts/examples/swap
bun install
export RPC_URL="your-solana-rpc-url"
```

The example already includes all necessary dependencies:

* `@jup-ag/api` for Jupiter API integration
* `@swig-wallet/classic` for Swig wallet functionality
* `@solana/web3.js` for Solana interactions
* `@solana/spl-token` for token account management
* `chalk` for colorful console output

## Understanding the Code

The example demonstrates several key concepts:

1. Setting up Swig with proper compute budget handling
2. Managing token accounts (ATAs)
3. Using Jupiter's API for quotes and swap instructions
4. Properly separating and signing instructions
5. Using utility functions for common operations

### Utility Functions

The example includes several helper functions to simplify common operations:

```typescript theme={null}
// Helper function to send transactions
async function sendTransaction(
  connection: Connection,
  instructions: TransactionInstruction[],
  payer: Keypair,
): Promise<string> {
  const tx = new Transaction().add(...instructions);
  tx.feePayer = payer.publicKey;
  tx.recentBlockhash = (await connection.getLatestBlockhash()).blockhash;
  tx.sign(payer);
  const sig = await connection.sendRawTransaction(tx.serialize());
  await connection.confirmTransaction(sig);
  return sig;
}

// Helper function to convert Jupiter instructions
function toTransactionInstruction(instruction: any): TransactionInstruction {
  return new TransactionInstruction({
    programId: new PublicKey(instruction.programId),
    keys: instruction.accounts.map((k: any) => ({
      pubkey: new PublicKey(k.pubkey),
      isSigner: k.isSigner,
      isWritable: k.isWritable,
    })),
    data: Buffer.from(instruction.data, 'base64'),
  });
}

// Helper function to format numbers with commas
function formatNumber(n: number) {
  return n.toString().replace(/\B(?=(\d{3})+(?!\d))/g, ',');
}

// Helper function to generate random bytes (for Swig ID)
function randomBytes(length: number): Uint8Array {
  const randomArray = new Uint8Array(length);
  crypto.getRandomValues(randomArray);
  return randomArray;
}
```

Let's break down the main components:

### 1. Creating and Getting the Swig Wallet Address

After creating your Swig account, you need to get the wallet address which is used for all transfers and token operations:

```typescript theme={null}
import {
  fetchSwig,
  findSwigPda,
  getSwigWalletAddress,
  getCreateSwigInstruction,
} from '@swig-wallet/classic';

// Create or find your Swig account
const id = randomBytes(32);
const swigAccountAddress = findSwigPda(id);

// Create the Swig (if new)
const createIx = await getCreateSwigInstruction({
  payer: rootUser.publicKey,
  actions: rootActions,
  authorityInfo: createEd25519AuthorityInfo(rootUser.publicKey),
  id,
});
await sendTransaction(connection, [createIx], rootUser);

// Fetch the Swig account and get the wallet address
const swig = await fetchSwig(connection, swigAccountAddress);
const swigWalletAddress = await getSwigWalletAddress(swig);
console.log('Swig wallet address:', swigWalletAddress.toBase58());
```

**Important**: Always use `swigWalletAddress` (not `swigAccountAddress`) for all transfer operations, token accounts, and Jupiter swaps.

### 2. Setting Up Token Accounts

<Note>
  This isnt technically necessary, but we leave it here for your benefit. Jupiter will create the token accounts for you if they don't exist in the setup instructions that are returned from the Jupiter API.
</Note>

Before swapping, we need to ensure the Swig wallet has the necessary token accounts (both USDC and Wrapped SOL):

```typescript theme={null}
const usdcMint = new PublicKey(
  'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v',
);
const wrappedSolMint = new PublicKey(
  'So11111111111111111111111111111111111111112',
);

// Check if Swig has USDC ATA
const swigUsdcAta = await getAssociatedTokenAddress(
  usdcMint,
  swigWalletAddress,
  true,
);
try {
  await getAccount(connection, swigUsdcAta);
  console.log(
    chalk.green('✓ USDC ATA exists:'),
    chalk.cyan(swigUsdcAta.toBase58()),
  );
} catch {
  const createAtaIx = createAssociatedTokenAccountInstruction(
    rootUser.publicKey,
    swigUsdcAta,
    swigWalletAddress,
    usdcMint,
  );
  await sendTransaction(connection, [createAtaIx], rootUser);
  console.log(
    chalk.green('✓ Created USDC ATA:'),
    chalk.cyan(swigUsdcAta.toBase58()),
  );
}

// Check if Swig has Wrapped SOL ATA
const swigWrappedSolAta = await getAssociatedTokenAddress(
  wrappedSolMint,
  swigWalletAddress,
  true,
);
try {
  await getAccount(connection, swigWrappedSolAta);
  console.log(
    chalk.green('✓ Wrapped SOL ATA exists:'),
    chalk.cyan(swigWrappedSolAta.toBase58()),
  );
} catch {
  const createAtaIx = createAssociatedTokenAccountInstruction(
    rootUser.publicKey,
    swigWrappedSolAta,
    swigWalletAddress,
    wrappedSolMint,
  );
  await sendTransaction(connection, [createAtaIx], rootUser);
  console.log(
    chalk.green('✓ Created Wrapped SOL ATA:'),
    chalk.cyan(swigWrappedSolAta.toBase58()),
  );
}
```

### 3. Getting Jupiter Quote

```typescript theme={null}
const transferAmount = 0.01 * LAMPORTS_PER_SOL;

const jupiter = createJupiterApiClient();
const quote = await jupiter.quoteGet({
  inputMint: wrappedSolMint.toBase58(),
  outputMint: usdcMint.toBase58(),
  amount: Math.floor(transferAmount),
  slippageBps: 50,
  maxAccounts: 64,
});

if (!quote) {
  console.log(chalk.red('❌ No quote available'));
  return;
}

console.log(chalk.blue('📊 Quote received:'));
console.log(`   Input: ${formatNumber(Number(quote.inAmount))} lamports`);
console.log(`   Output: ${formatNumber(Number(quote.outAmount))} USDC (raw)`);
```

### 4. Handling Compute Budget and Instructions

The most critical part is properly separating and handling instructions:

```typescript theme={null}
const swapInstructionsRes = await jupiter.swapInstructionsPost({
  swapRequest: {
    quoteResponse: quote,
    userPublicKey: swigWalletAddress.toBase58(),
    wrapAndUnwrapSol: true,
    useSharedAccounts: true,
  },
});

const swapInstructions: TransactionInstruction[] = [
  ...(swapInstructionsRes.setupInstructions || []).map(
    toTransactionInstruction,
  ),
  toTransactionInstruction(swapInstructionsRes.swapInstruction),
];

// Sign instructions with Swig
const rootRole = swig.findRolesByEd25519SignerPk(rootUser.publicKey)[0];
const signIxs = await getSignInstructions(
  swig,
  rootRole.id,
  swapInstructions,
);
```

### 5. Creating and Sending the Transaction

```typescript theme={null}
const lookupTables = await Promise.all(
  swapInstructionsRes.addressLookupTableAddresses.map(async (addr) => {
    const res = await connection.getAddressLookupTable(new PublicKey(addr));
    return res.value!;
  }),
);

const { blockhash, lastValidBlockHeight } =
  await connection.getLatestBlockhash();
const outerIxs = [
  ComputeBudgetProgram.setComputeUnitLimit({ units: 150_000 }),
  ComputeBudgetProgram.setComputeUnitPrice({ microLamports: 50 }),
];

const messageV0 = new TransactionMessage({
  payerKey: rootUser.publicKey,
  recentBlockhash: blockhash,
  instructions: [...outerIxs, ...signIxs],
}).compileToV0Message(lookupTables);

const tx = new VersionedTransaction(messageV0);
tx.sign([rootUser]);

const signature = await connection.sendTransaction(tx, {
  skipPreflight: true,
  preflightCommitment: 'confirmed',
});

const result = await connection.confirmTransaction({
  signature,
  blockhash,
  lastValidBlockHeight,
});

if (result.value.err) {
  throw new Error(`Transaction failed: ${JSON.stringify(result.value.err)}`);
}

const postSwapBalance = await connection.getTokenAccountBalance(swigUsdcAta);
console.log(chalk.green('🎉 Swap successful!'));
console.log(chalk.gray(`   Signature: ${signature}`));
console.log(
  chalk.blue(`💰 New USDC balance: ${postSwapBalance.value.uiAmount}`),
);
```

## Important Considerations

1. **Compute Budget Management**:
   * Set appropriate compute unit limit and price
   * These instructions must be outside of Swig-signed instructions

2. **Account Management**:
   * Create ATAs in separate transactions before swapping
   * Account for Swig's overhead when setting `maxAccounts`

3. **Transaction Structure**:
   * Properly separate outer instructions from Swig-signed instructions
   * Use `getSignInstructions` to sign all Swig instructions at once
   * Use versioned transactions with address lookup tables

4. **Error Handling**:
   * Verify ATA existence and creation
   * Check transaction confirmation status
   * Verify token balances after swap

## Running the Example

1. Prepare your keypair file
2. Run the example:

```bash theme={null}
bun run index.ts path/to/keypair.json [optional-swig-address]
```

The example will:

* Create or use an existing Swig wallet
* Set up necessary token accounts
* Get the best swap route from Jupiter
* Execute the swap with proper instruction handling

## Production Considerations

1. **Security**:
   * Securely manage keypairs and private keys
   * Implement proper error recovery mechanisms
   * Add transaction timeout handling

2. **Performance**:
   * Adjust compute budget based on swap complexity
   * Consider using RPC endpoints with higher rate limits
   * Implement proper retry mechanisms

3. **User Experience**:
   * Add progress indicators for multi-step operations
   * Implement proper balance checking and updates
   * Add slippage protection options

For more information, check out:

* [Jupiter API Documentation](https://station.jup.ag/docs/apis/overview)
* [Swig Documentation](https://docs.swig.rs/)


# Transferring stuff with Swig
Source: https://build.onswig.com/examples/transfer

\"Give and it will be given to you\" - Ancient Green Manuscripts

This guide walks through different ways to perform transfers using Swig, progressing from basic to more advanced patterns.
You can find all example code in the [swig-ts/examples/basic/classic](https://github.com/anagrambuild/swig-ts/tree/main/examples/basic/classic) directory or for kit refer to this directory [swig-ts/examples/basic/kit](https://github.com/anagrambuild/swig-ts/tree/main/examples/basic/kit).

<Tip>Examples with svm in the file name use LiteSVM for testing. Those without svm in the file name use a local validator. Which you can run with the `bun start-validator` command.</Tip>

## Basic Transfer with Ed25519 Keys

The simplest way to use Swig is with standard Ed25519 keypairs. Here are the key parts:

<Tabs>
  <Tab title="Classic">
    ```ts theme={null}
    // Key Setup - Using standard Solana keypairs
    const userRootKeypair = Keypair.generate();
    const dappAuthorityKeypair = Keypair.generate();

    // Create a new Swig account with root authority
    const rootActions = Actions.set().all().get();
    const createSwigInstruction = await getCreateSwigInstruction({
      payer: userRootKeypair.publicKey,
      authorityInfo: createEd25519AuthorityInfo(userRootKeypair.publicKey),
      id,
      actions: rootActions,
    });

    // Fetch the Swig account and get the wallet address
    const swig = await fetchSwig(connection, swigAccountAddress);
    const swigWalletAddress = await getSwigWalletAddress(swig);

    // Add a new authority with a spending limit
    const dappActions = Actions.set().solLimit({ amount: BigInt(0.1 * LAMPORTS_PER_SOL) }).get();
    const addAuthorityInstructions = await getAddAuthorityInstructions(
      swig,
      rootRole.id,
      createEd25519AuthorityInfo(dappAuthorityKeypair.publicKey),
      dappActions,
    );

    // Transfer SOL with Swig authority (use swigWalletAddress, not swigAccountAddress)
    const transferIx = SystemProgram.transfer({
      fromPubkey: swigWalletAddress,
      toPubkey: dappAuthorityKeypair.publicKey,
      lamports: 0.1 * LAMPORTS_PER_SOL,
    });

    const signedInstructions = await getSignInstructions(
      swig,
      dappRole.id,
      [transferIx]
    );

    await sendTransaction(connection, signedInstructions, dappAuthorityKeypair);
    ```
  </Tab>

  <Tab title="Kit">
    ```ts theme={null}
    // Key Setup - Using @solana/kit KeyPairSigner
    const userRoot = await generateKeyPairSigner();
    const dappAuthority = await generateKeyPairSigner();

    // Create Swig with Ed25519 authority
    const rootActions = Actions.set().all().get();
    const createSwigInstruction = await getCreateSwigInstruction({
      payer: userRoot.address,
      authorityInfo: createEd25519AuthorityInfo(userRoot.address),
      id,
      actions: rootActions,
    });

    // Fetch the Swig account and get the wallet address
    const swig = await fetchSwig(connection.rpc, swigAccountAddress);
    const swigWalletAddress = await getSwigWalletAddress(swig);

    // Add a dapp authority with spending limit
    const dappActions = Actions.set().solLimit({ amount: BigInt(0.1 * LAMPORTS_PER_SOL) }).get();
    const addAuthorityInstructions = await getAddAuthorityInstructions(
      swig,
      rootRole.id,
      createEd25519AuthorityInfo(dappAuthority.address),
      dappActions,
    );

    // Transfer SOL (use swigWalletAddress, not swigAccountAddress)
    const transferInstruction = getSolTransferInstruction({
      fromAddress: swigWalletAddress,
      toAddress: dappAuthority.address,
      lamports: 0.1 * LAMPORTS_PER_SOL,
    });

    const signedInstructions = await getSignInstructions(
      swig,
      dappRole.id,
      [transferInstruction],
    );

    await sendTransaction(connection, signedInstructions, dappAuthority);
    ```
  </Tab>
</Tabs>

You can find the complete example in `transfer-local.ts` and `transfer-svm.ts` for local and LiteSVM environments respectively.

***

## Using Secp256k1 Keys (EVM Compatible)

For EVM compatibility, Swig supports Secp256k1 keys. Note the key differences from the Ed25519 example:

<Tabs>
  <Tab title="Classic">
    ```ts theme={null}
    // Key Setup - Using Ethereum wallet
    const userWallet = Wallet.generate(); // 👈 EVM wallet instead of Solana Keypair

    // Connect to network and create payers
    const connection = new Connection('http://localhost:8899', 'confirmed');
    const payer = Keypair.generate();
    await connection.requestAirdrop(payer.publicKey, LAMPORTS_PER_SOL);
    const signer = Keypair.generate();
    await connection.requestAirdrop(signer.publicKey, LAMPORTS_PER_SOL);

    // Find Swig PDA by ID
    const id = Uint8Array.from(Array(32).fill(1)); // use any 32-byte identifier
    const swigAccountAddress = findSwigPda(id);

    // Create Swig with Secp256k1 authority
    const rootActions = Actions.set().all().get();
    const createSwigInstruction = await getCreateSwigInstruction({
      authorityInfo: createSecp256k1AuthorityInfo(userWallet.getPublicKey()),
      id,
      payer: payer.publicKey,
      actions: rootActions,
    });

    // Fetch the Swig account and get the wallet address
    const swig = await fetchSwig(connection, swigAccountAddress);
    const swigWalletAddress = await getSwigWalletAddress(swig);

    // Prepare transfer (use swigWalletAddress, not swigAccountAddress)
    const transfer = SystemProgram.transfer({
      fromPubkey: swigWalletAddress,
      toPubkey: dappTreasury,
      lamports: 0.1 * LAMPORTS_PER_SOL,
    });

    // Prepare transfer
    const transfer = SystemProgram.transfer({
      fromPubkey: swigAddress,
      toPubkey: dappTreasury,
      lamports: 0.1 * LAMPORTS_PER_SOL,
    });

    // Sign using the Secp256k1 private key
    const signingFn = getSigningFnForSecp256k1PrivateKey(
      userWallet.getPrivateKey(),
    );
    const slot = await connection.getSlot('finalized');

    const signedTransfer = await getSignInstructions(
      swig,
      rootRole.id,
      [transfer],
      false,
      {
        currentSlot: BigInt(slot),
        signingFn,
        payer: signer.publicKey,
      },
    );
    ```
  </Tab>

  <Tab title="Kit">
    ```ts theme={null}
    // Key Setup - Using Ethereum wallet
    const userWallet = Wallet.generate(); // 👈 EVM wallet instead of Solana keypair

    // RPC Setup
    const rpc = createSolanaRpc('http://localhost:8899');
    const rpcSubscriptions = createSolanaRpcSubscriptions('ws://localhost:8900');
    const connection = { rpc, rpcSubscriptions };

    // Solana accounts for fees and transactions
    const payer = await generateKeyPairSigner();
    const signer = await generateKeyPairSigner();
    const dappTreasury = await generateKeyPairSigner();

    // Find Swig PDA by ID
    const id = Uint8Array.from(Array(32).fill(1));
    const swigAccountAddress = await findSwigPda(id);

    // Create Swig with Secp256k1 authority
    const rootActions = Actions.set().all().get();
    const createSwigIx = await getCreateSwigInstruction({
      authorityInfo: createSecp256k1AuthorityInfo(userWallet.getPublicKey()),
      id,
      payer: payer.address,
      actions: rootActions,
    });

    // Fetch the Swig account and get the wallet address
    const swig = await fetchSwig(connection.rpc, swigAccountAddress);
    const swigWalletAddress = await getSwigWalletAddress(swig);

    // Prepare transfer instruction (use swigWalletAddress, not swigAccountAddress)
    const transfer = {
      programAddress: SYSTEM_PROGRAM_ADDRESS,
      accounts: [
        {
          address: swigWalletAddress,
          role: AccountRole.WRITABLE_SIGNER,
        },
        {
          address: dappTreasury.address,
          role: AccountRole.WRITABLE,
        },
      ],
      data: new Uint8Array(
        getTransferSolInstructionDataEncoder().encode({
          amount: 100_000_000, // 0.1 SOL
        }),
      ),
    };

    // Sign using Secp256k1 private key
    const currentSlot = await rpc.getSlot().send();
    const signingFn = getSigningFnForSecp256k1PrivateKey(userWallet.getPrivateKey());

    const signIx = await getSignInstructions(swig, rootRole.id, [transfer], false, {
      payer: signer.address,
      currentSlot,
      signingFn,
    });
    ```
  </Tab>
</Tabs>

Check out `transfer-local-secp.ts` and `transfer-svm-secp.ts` for complete examples.

***

## Using Viem for Ethereum Wallet Integration

For a more complete Ethereum wallet integration using Viem:

```ts theme={null}
// Using Viem account
const privateKeyAccount = privateKeyToAccount(userWallet.getPrivateKeyString());

const swigAccountAddress = findSwigPda(id);
const rootActions = Actions.set().all().get();

const createSwigInstruction = await getCreateSwigInstruction({
  authorityInfo: createSecp256k1AuthorityInfo(privateKeyAccount.publicKey),
  id,
  payer: transactionPayer.publicKey,
  actions: rootActions,
});

sendSVMTransaction(svm, [createSwigInstruction], transactionPayer);

let swig = fetchSwig(svm, swigAccountAddress);
const swigWalletAddress = await getSwigWalletAddress(swig);
svm.airdrop(swigWalletAddress, BigInt(LAMPORTS_PER_SOL));

let rootRole = swig.findRolesBySecp256k1SignerAddress(privateKeyAccount.address)[0];
if (!rootRole) throw new Error('Role not found for authority');

const viemSign: SigningFn = async (message: Uint8Array) => {
  const sig = await privateKeyAccount.sign({ hash: keccak256(message) });
  return { signature: hexToBytes(sig) };
};

const transfer = SystemProgram.transfer({
  fromPubkey: swigAddress,
  toPubkey: dappTreasury,
  lamports: 0.1 * LAMPORTS_PER_SOL,
});

let signTransfer = await getSignInstructions(swig, rootRole.id, [transfer], false, {
  currentSlot: svm.getClock().slot,
  signingFn: viemSign,
  payer: transactionPayer.publicKey,
});

sendSVMTransaction(svm, signTransfer, transactionPayer);

const viemSignWithPrefix: SigningFn = async (message: Uint8Array) => {
  const prefix = getEvmPersonalSignPrefix(message.length);
  const prefixedMessage = new Uint8Array(prefix.length + message.length);

  prefixedMessage.set(prefix);
  prefixedMessage.set(message, prefix.length);

  const sig = await privateKeyAccount.sign({ hash: keccak256(prefixedMessage) });
  return { signature: hexToBytes(sig), prefix };
};

signTransfer = await getSignInstructions(swig, rootRole.id, [transfer], false, {
  currentSlot: svm.getClock().slot,
  signingFn: viemSignWithPrefix,
  payer: transactionPayer.publicKey,
});

sendSVMTransaction(svm, signTransfer, transactionPayer);

const viemSignMessage: SigningFn = async (message: Uint8Array) => {
  const sig = await privateKeyAccount.signMessage({ message: { raw: message } });
  return {
    signature: hexToBytes(sig),
    prefix: getEvmPersonalSignPrefix(message.length),
  };
};

signTransfer = await getSignInstructions(swig, rootRole.id, [transfer], false, {
  currentSlot: svm.getClock().slot,
  signingFn: viemSignMessage,
  payer: transactionPayer.publicKey,
});

sendSVMTransaction(svm, signTransfer, transactionPayer);
```

See `transfer-svm-viem.ts` for the full working code.

***

## Using Sessions for Enhanced Security

Sessions allow limited, temporary authority:

### Ed25519 Sessions

<Tabs>
  <Tab title="Classic">
    ```ts theme={null}
    // Key Setup
    const userRootKeypair = Keypair.generate();
    const dappSessionKeypair = Keypair.generate();

    // Create Swig with Session Authority
    const createSwigIx = await getCreateSwigInstruction({
      id,
      authorityInfo: createEd25519SessionAuthorityInfo(
        userRootKeypair.publicKey,
        100n, // session duration in slots
      ),
      actions: rootActions,
      payer: userRootKeypair.publicKey,
    });

    // Create Session for dApp
    const createSessionIx = await getCreateSessionInstructions(
      swig,
      rootRole.id,
      dappSessionKeypair.publicKey,
      50n, // session duration
    );

    // Fetch the Swig account and get the wallet address
    const swigWalletAddress = await getSwigWalletAddress(swig);

    // Find and use session role
    const sessionRole = swig.findRoleBySessionKey(dappSessionKeypair.publicKey);
    if (!sessionRole || !sessionRole.isSessionBased()) {
      throw new Error('Invalid session role');
    }

    // Create transfer using swigWalletAddress
    const transfer = SystemProgram.transfer({
      fromPubkey: swigWalletAddress,
      toPubkey: dappTreasury,
      lamports: 0.1 * LAMPORTS_PER_SOL,
    });

    // Sign with session key
    const signedTransfer = await getSignInstructions(
      swig,
      sessionRole.id,
      [transfer],
      false,
      { payer: dappSessionKeypair.publicKey },
    );
    ```
  </Tab>

  <Tab title="Kit">
    ```ts theme={null}
    // Key Setup
    const userRootKeypair = await generateKeyPairSigner();
    const dappSessionKeypair = await generateKeyPairSigner();

    // Create Swig with Session Authority
    const createSwigIx = await getCreateSwigInstruction({
      id,
      authorityInfo: createEd25519SessionAuthorityInfo(
        userRootKeypair.address,
        100n, // session duration in slots
      ),
      actions: rootActions,
      payer: userRootKeypair.address,
    });

    // Create Session for dApp
    const createSessionIx = await getCreateSessionInstructions(
      swig,
      rootRole.id,
      dappSessionKeypair.address,
      50n, // session duration
    );

    // Fetch the Swig account and get the wallet address
    const swigWalletAddress = await getSwigWalletAddress(swig);

    // Find and use session role
    const sessionRole = swig.findRolesByEd25519SignerPk(dappSessionKeypair.address)[0];
    if (!sessionRole || !sessionRole.isSessionBased()) {
      throw new Error('Invalid session role');
    }

    // Create transfer using swigWalletAddress
    const transferIx = getSolTransferInstruction({
      fromAddress: swigWalletAddress,
      toAddress: dappTreasury.address,
      lamports: 0.1 * LAMPORTS_PER_SOL,
    });

    // Sign with session key
    const signedTransferIx = await getSignInstructions(
      swig,
      sessionRole.id,
      [transferIx],
      false,
      { payer: dappSessionKeypair.address },
    );
    ```
  </Tab>
</Tabs>

### Secp256k1 Sessions

<Tabs>
  <Tab title="Classic">
    ```ts theme={null}
    // Key Setup - EVM wallet with session capability
    const userWallet = Wallet.generate();
    const userRootKeypair = Keypair.generate();
    const dappSessionKeypair = Keypair.generate();

    // Create Swig with Secp256k1 Session Authority
    const createSwigInstruction = await getCreateSwigInstruction({
      authorityInfo: createSecp256k1SessionAuthorityInfo(
        userWallet.getPublicKey(),
        100n, // max session duration in slots
      ),
      id,
      payer: userRootKeypair.publicKey,
      actions: rootActions,
    });

    // Create Session with EVM signing
    const signingFn = getSigningFnForSecp256k1PrivateKey(
      userWallet.getPrivateKeyString(),
    );
    const currentSlot = await connection.getSlot('confirmed');

    const sessionInstructions = await getCreateSessionInstructions(
      swig,
      rootRole.id,
      dappSessionKeypair.publicKey,
      50n, // session duration
      {
        currentSlot: BigInt(currentSlot),
        signingFn,
        payer: userRootKeypair.publicKey,
      },
    );

    // Fetch the Swig account and get the wallet address
    const swigWalletAddress = await getSwigWalletAddress(swig);

    // Find and use session role
    const sessionRole = swig.findRoleBySessionKey(dappSessionKeypair.publicKey);
    if (!sessionRole) throw new Error('Session role not found');

    // Create transfer using swigWalletAddress
    const transferIx = SystemProgram.transfer({
      fromPubkey: swigWalletAddress,
      toPubkey: dappTreasury,
      lamports: 0.1 * LAMPORTS_PER_SOL,
    });

    // Sign with session key
    const signTransfer = await getSignInstructions(
      swig,
      sessionRole.id,
      [transferIx],
      false,
      {
        currentSlot: BigInt(currentSlot),
        signingFn,
        payer: dappSessionKeypair.publicKey,
      },
    );
    ```
  </Tab>

  <Tab title="Kit">
    ```ts theme={null}
    // Key Setup - EVM wallet with session capability
    const userWallet = Wallet.generate();
    const userRootKeypair = await generateKeyPairSigner();
    const dappSessionKeypair = await generateKeyPairSigner();

    // Create Swig with Secp256k1 Session Authority
    const authorityInfo = createSecp256k1SessionAuthorityInfo(
      userWallet.getPublicKey(),
      100n, // max session duration in slots
    );

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

    // Create Session with EVM signing
    const signingFn = getSigningFnForSecp256k1PrivateKey(userWallet.getPrivateKey());
    const currentSlot = await rpc.getSlot().send();

    const sessionInstructions = await getCreateSessionInstructions(
      swig,
      rootRole.id,
      dappSessionKeypair.address,
      50n, // session duration
      { 
        payer: userRootKeypair.address,
        currentSlot,
        signingFn,
      },
    );

    // Fetch the Swig account and get the wallet address
    const swigWalletAddress = await getSwigWalletAddress(swig);

    // Find and use session role
    const sessionRole = swig.findRoleBySessionKey(dappSessionKeypair.address);
    if (!sessionRole) throw new Error('Session role not found');

    // Create transfer using swigWalletAddress
    const transferIx = getSolTransferInstruction({
      fromAddress: swigWalletAddress,
      toAddress: dappTreasury.address,
      lamports: 0.1 * LAMPORTS_PER_SOL,
    });

    // Sign with session key
    const signTransfer = await getSignInstructions(
      swig,
      sessionRole.id,
      [transferIx],
      false,
      {
        payer: dappSessionKeypair.address,
        currentSlot,
        signingFn,
      },
    );
    ```
  </Tab>
</Tabs>

***

## Key aspects of sessions:

* Can be created with any supported authority type (Ed25519, Secp256k1)
* Limited duration specified in slots
* Restricted set of actions (defined by sessionActions)
* Perfect for dApp integrations where temporary access is needed

You can find complete session examples in (we have just mentioned a few you can find all of them labelled a specific way but it will contain the word "sessions" in the file name):

* `transfer-local-session.ts` (Ed25519)
* `transfer-svm-session.ts` (Ed25519)
* `transfer-svm-secp-session.ts` (Secp256k1)

For more detailed information about sessions, check out the [Creating Sessions Guide](/examples/sessions).

***

## Testing Environment Options

These examples can be run in different environments:

**Local Validator**: Use the `transfer-local-*` examples

* Requires running a local Solana validator
* Real blockchain environment
* Good for final testing

**LiteSVM**: Use the `transfer-svm-*` examples

* No validator required
* Instant transaction confirmation
* Perfect for rapid development
* Simulates the Solana runtime

**Devnet**: All examples work with devnet

* Change connection URL to `https://api.devnet.solana.com`
* Real network environment
* Free to use with airdropped SOL

LiteSVM is recommended for initial development as it provides the fastest feedback loop. Move to local validator or devnet for more thorough testing.


# V2 Protocol Features
Source: https://build.onswig.com/examples/v2_features

Examples showcasing Swig SDK v2 protocol improvements and automatic version detection

# Swig SDK V2 Protocol Features

This guide demonstrates the key features introduced in Swig SDK v2, including automatic version detection, enhanced account structure, and improved instruction handling.

## Automatic Version Detection

The SDK automatically detects whether a Swig account is v1 or v2:

```typescript theme={null}
import { fetchSwigAccount } from '@swig-wallet/classic';

// Fetch any Swig account
const swig = await fetchSwigAccount(connection, swigAccountAddress);

// Automatic version detection
const version = swig.accountVersion(); // Returns 'v1' | 'v2'
console.log(`Account version: ${version}`);

// Automatic wallet address resolution
const walletAddress = await getSwigWalletAddress(swig);
// For v1: returns account address directly
// For v2: returns system program derived address
```

## Enhanced Account Structure

V2 accounts use an optimized structure with PDA-based addressing:

```typescript theme={null}
// Version detection logic
if (swig.accountVersion() === 'v2') {
  // V2 account uses bump seed and PDA-derived wallet address
  const accountPda = getSwigAccountAddressRaw(swig); // The account PDA
  const systemWallet = await getSwigSystemAddressRaw(swig); // System-derived wallet
  
  console.log(`Account PDA: ${accountPda.toBase58()}`);
  console.log(`System wallet: ${systemWallet.toBase58()}`);
} else {
  // V1 account uses direct address
  const directAddress = getSwigAccountAddressRaw(swig);
  console.log(`Direct address: ${directAddress.toBase58()}`);
}
```

## Automatic Instruction Selection

The SDK automatically chooses the correct instruction type based on account version:

```typescript theme={null}
import { 
  getSignInstructions,
  SystemProgram,
  LAMPORTS_PER_SOL 
} from '@swig-wallet/classic';

// This works for both v1 and v2 accounts
const signInstructions = await getSignInstructions(
  swig,
  0, // role id
  [
    SystemProgram.transfer({
      fromPubkey: await getSwigWalletAddress(swig), // Auto-resolves correct address
      toPubkey: recipient,
      lamports: BigInt(LAMPORTS_PER_SOL / 2),
    }),
  ]
);

// SDK automatically uses:
// - signV2 instruction for v2 accounts
// - sign instruction for v1 accounts
```

## Complete V2 Example

Here's a complete example demonstrating v2 features:

```typescript theme={null}
import {
  Connection,
  Keypair,
  SystemProgram,
  LAMPORTS_PER_SOL,
  Transaction,
} from '@solana/web3.js';
import {
  Actions,
  createEd25519AuthorityInfo,
  fetchSwigAccount,
  getCreateSwigInstruction,
  getAddAuthorityInstructions,
  getSignInstructions,
  findSwigPda,
} from '@swig-wallet/classic';

async function demonstrateV2Features() {
  const connection = new Connection('https://api.devnet.solana.com');
  
  // Setup keypairs
  const userKeypair = Keypair.generate();
  const authorityKeypair = Keypair.generate();
  const recipientKeypair = Keypair.generate();
  
  // Fund the user account
  const airdropSignature = await connection.requestAirdrop(
    userKeypair.publicKey,
    2 * LAMPORTS_PER_SOL
  );
  await connection.confirmTransaction(airdropSignature);
  
  // Create a new Swig account
  const swigId = Keypair.generate().publicKey;
  const swigAccountAddress = findSwigPda(swigId);
  
  const createInstructions = getCreateSwigInstruction(
    userKeypair.publicKey,
    swigId,
    Actions.set().all().get(),
    createEd25519AuthorityInfo({
      id: userKeypair.publicKey,
      signer: userKeypair.publicKey,
    })
  );
  
  // Create the account
  const createTx = new Transaction().add(...createInstructions);
  createTx.feePayer = userKeypair.publicKey;
  createTx.recentBlockhash = (await connection.getLatestBlockhash()).blockhash;
  createTx.sign(userKeypair);
  
  await connection.sendAndConfirmTransaction(createTx, [userKeypair]);
  
  // Fetch the created account and check version
  const swig = await fetchSwigAccount(connection, swigAccountAddress);
  console.log(`Created account version: ${swig.accountVersion()}`);
  console.log(`Wallet address: ${(await getSwigWalletAddress(swig)).toBase58()}`);
  
  // Add an authority with automatic program action management
  const addAuthorityInstructions = await getAddAuthorityInstructions(
    swig,
    0, // root role
    createEd25519AuthorityInfo({
      id: authorityKeypair.publicKey,
      signer: authorityKeypair.publicKey,
    }),
    Actions.set().manageAuthority().get()
  );
  
  const addAuthorityTx = new Transaction().add(...addAuthorityInstructions);
  addAuthorityTx.feePayer = userKeypair.publicKey;
  addAuthorityTx.recentBlockhash = (await connection.getLatestBlockhash()).blockhash;
  addAuthorityTx.sign(userKeypair);
  
  await connection.sendAndConfirmTransaction(addAuthorityTx, [userKeypair]);
  
  // Perform a transfer using automatic instruction selection
  const transferInstructions = await getSignInstructions(
    swig,
    0, // role id
    [
      SystemProgram.transfer({
        fromPubkey: await getSwigWalletAddress(swig), // Auto-resolves correct address
        toPubkey: recipientKeypair.publicKey,
        lamports: BigInt(LAMPORTS_PER_SOL / 4),
      }),
    ]
  );
  
  const transferTx = new Transaction().add(...transferInstructions);
  transferTx.feePayer = userKeypair.publicKey;
  transferTx.recentBlockhash = (await connection.getLatestBlockhash()).blockhash;
  transferTx.sign(userKeypair);
  
  await connection.sendAndConfirmTransaction(transferTx, [userKeypair]);
  
  console.log('Transfer completed successfully!');
  
  // Check final balances
  const walletBalance = await connection.getBalance(await getSwigWalletAddress(swig));
  const recipientBalance = await connection.getBalance(recipientKeypair.publicKey);
  
  console.log(`Wallet balance: ${walletBalance / LAMPORTS_PER_SOL} SOL`);
  console.log(`Recipient balance: ${recipientBalance / LAMPORTS_PER_SOL} SOL`);
}

// Run the example
demonstrateV2Features().catch(console.error);
```

## Enhanced Program Action Management

V2 includes automatic program action management:

```typescript theme={null}
import { Actions, ensureProgramAction } from '@swig-wallet/lib';

// The SDK automatically ensures proper program actions
const actions = Actions.set().manageAuthority().get();

// ensureProgramAction is called automatically in instruction builders
// It adds ProgramAll action if no program permissions exist
const enhancedActions = ensureProgramAction(actions);

// Use in authority management
const addAuthorityInstructions = await getAddAuthorityInstructions(
  swig,
  roleId,
  authorityInfo,
  enhancedActions // Automatically enhanced with program permissions
);
```

## Version-Aware Development

Best practices for working with both v1 and v2 accounts:

```typescript theme={null}
// Always use walletAddress() instead of direct account access
const walletAddress = await getSwigWalletAddress(swig);

// Check version when debugging
if (swig.accountVersion() === 'v2') {
  console.log('Using v2 account with PDA-based addressing');
  console.log('Account PDA:', getSwigAccountAddressRaw(swig).toBase58());
  console.log('System address:', (await getSwigSystemAddressRaw(swig)).toBase58());
} else {
  console.log('Using v1 account with direct addressing');
  console.log('Account address:', getSwigAccountAddressRaw(swig).toBase58());
}

// Let the SDK handle instruction selection automatically
const instructions = await getSignInstructions(swig, roleId, innerInstructions);
// No need to specify instruction version - it's automatic!
```

## Key Benefits

### Backward Compatibility

* All existing v1 code works without changes
* Automatic version detection eliminates manual configuration
* Same API surface for both account versions

### Performance Improvements

* V2 accounts use optimized storage structure
* PDA-based addressing provides better isolation
* Reduced account size and transaction costs

### Enhanced Developer Experience

* Automatic instruction selection
* Built-in program action management
* Version-aware debugging utilities

***

The v2 protocol improvements provide enhanced performance and developer experience while maintaining full backward compatibility with existing Swig applications.


# Swig: Smart Wallet Tooling for Solana
Source: https://build.onswig.com/index

Swig is a powerful account abstraction toolkit that enables developers to create advanced, programmable Solana smart wallets with features like delegated access controls, fine-grained permissions, social recovery, and cross-chain compatibility.

## **What is Swig?**

Swig is an account abstraction toolkit that empowers developers to create sophisticated, programmable smart wallets on Solana. It’s powerful, open-sourced, and fast to build on - most use cases can be built on Swig in \<30 minutes.

Smart wallet functionality has been popular on EVM chains, but less developed on Solana. Swig changes that. Developers can now build smarter on Solana with Swig. See how below.

### **Current Market Problems**

Developments in Web3 have brought many benefits, but simultaneously some table stakes Web2 functions have been lost along the way. Traditional crypto wallets are part of this problem:

* **Poor UX:** Traditional wallets force users to either give up full control or do everything manually themselves. You could be the best dev, but your app’s experience would inherently be downgraded as a result.
* **Payments:** While crypto solves many payments challenges, the automated and configurable transaction tooling critical for most payments use cases is still limited.
* **General Abstraction:** Developers need to rely on users who are blockchain experts to gain traction on their apps due to limited abstraction tooling in the market.
* **Onboarding:** Seed phrases, onramps, and gas all make onboarding to a new app complicated. Devs are losing the battle before it even starts.

Smart wallets solve these problems, but while smart wallets have seen widespread adoption on Ethereum, Solana has remained underserved - until now.

### **How Swig Solves These Problems**

A Swig wallet is an on-chain account built inside a Solana program that can perform all standard wallet functions while adding powerful programmable features:

| Swig Features                                                                                                                       | Pre-Swig Paradigm                                                                                                                                     | Post-Swig Paradigm                                                                                                                                        |
| :---------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **🗝️ Non-Custodial Smart Wallets** <br /> *Devs can create Web2 UX without sacrificing on Web3 self-custody standards*             | **Custody vs. UX Tradeoff** <br />❌ Devs choose between: Self-custody, but complex UX <br />Or<br />❌ Custodial services, but security risks          | **Web2 UX + Web3 Self-Custody Control** <br />✅ Create embedded wallets with no intermediaries <br />✅ Apps can request permissions without managing keys |
| **⏳ Session-Based Authorization** <br /> *Enable temporary, permissioned app access without constant manual approvals*              | **Manual Approval Friction** <br />❌ Users manually approve every transaction <br />❌ Apps lose traction due to “approve fatigue”                     | **Seamless Session Mgmt**<br />✅ Users approve once per session period <br />✅ Configurable time limited permissions                                      |
| **🔓 Granular Permissions** <br /> *Delegate specific transaction permissions rather than full wallet control*                      | **All-or-Nothing Access** <br />❌ Wallets require full signing authority                                                                              | **Fine-Grained Controls** <br />✅ Role-based permissions <br />✅ Transaction-type permissions                                                             |
| **🔄 Automated Transactions** <br /> *Power subscription payments, payment streaming, and conditional transactions*                 | **Manual Payments**<br />❌ Payments are not programmable <br />❌ Advanced payment logic done off-chain                                                | **Programmable Payments**<br />✅ Subscription billing <br />✅ Payment streaming <br />✅ Automated rebalancing <br />✅ Dollar-cost averaging               |
| **🌐 Social Recovery & Authentication** <br /> *Manage wallets using social accounts like Google, X, or Facebook through ZK proofs* | **Seed Phrase Vulnerability & Onboarding Frictions** <br />❌ Complicated user onboarding <br />❌ No key recovery options                              | **Familiar Recovery & Onboarding Methods** <br />✅ Seamless Web2 user onboarding <br />✅ Multi-guardian recovery with trusted contacts                    |
| **⛓️ Chain Abstraction** <br /> *Operate seamlessly across multiple chains*                                                         | **Single Chain Limitations** <br />❌ Separate wallets needed for different chains                                                                     | **Unified Multi-Chain Experience**<br />✅ 1 wallet operates across all SVM chains <br />✅ Sign SVM transactions with EVM Keys                             |
| **⛽ Paymaster Integration** <br /> *Cover gas fees for users through a central account*                                             | **Gas Fee Barriers** <br />❌ Users must hold native SOL tokens for every trx <br />❌ High-friction onboarding <br />❌ App experiences can’t be “free” | **No Gas, No Problem** <br />✅ Apps cover gas for users <br />✅ Users can pay gas with other tokens <br />✅ “Freemium” app experiences possible           |

***

## **Why Swig Makes Solana More Powerful**

Solana combined with Swig is a game changer for developers.

|                             | Solana                                                                                                                                                                                                                                                               | Solana + Swig                                                                                                                                                |
| :-------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Payments Infrastructure** | Solana is emerging as a leader in payments due in large part to its fast transaction settlement speed                                                                                                                                                                | Swig expands on this by allowing developers to **abstract complexity** and create **powerful non-custodial payments solutions** for consumers and businesses |
| **Consumer Adoption**       | Solana is the hub for consumer apps                                                                                                                                                                                                                                  | Swig **dramatically improves UX** for Solana app developers by enhancing key management systems to enable **simple and secure product flows**                |
| **Performance at Scale**    | Solana’s fast transaction speeds and low fees make it particularly attractive for high-velocity trading and payment use cases But, legacy wallet experiences limit this performance advantage with constant manual approvals and limited transaction programmability | Swig’s optimized design **maintains Solana’s high speed and low fees**, even with advanced wallet features                                                   |

***

## **How Swig Works**

The Swig protocol operates through a role-based system that enables seamless interaction with various services and platforms on Solana. Each role has:

* An authority mechanism that can include social logins, blockchain keypairs, and other authentication methods
* A set of configurable permissions that control what actions can be taken
* Optional session-based authentication for enhanced security

This flexible architecture allows developers to create custom wallet solutions while maintaining security and user control. Whether you’re building DeFi apps, payment solutions, or next-generation consumer wallets, Swig provides the infrastructure needed to create powerful, user-friendly experiences.


# Swig MCP Support
Source: https://build.onswig.com/mcp-support

"Why build it yourself when AI can build it for you?" - Albert Einstein from the grave

## Overview

The Model Context Protocol (MCP) is an open protocol that connects your functions to LLMs and AI applications. With Mintlify's integration, you can automatically generate an MCP server for Swig's docs, enabling seamless AI-powered interactions with your product.

## Generating your MCP server

Swig docs can be converted into an MCP server using the following command:

```bash theme={null}
npx mint-mcp add build.onswig.com
```

You can also view an llms-full.txt file [here](https://build.onswig.com/llms-full.txt)

<Note>
  You can view the full documentation for Mintlify's MCP Configuration
  [here](https://mintlify.com/docs/mcp).
</Note>


# null
Source: https://build.onswig.com/reference/error-types/index



# Swig Wallet Error Reference

This document provides a comprehensive list of all error types used throughout the Swig wallet system, including their numeric codes and meanings.

For the complete source code and latest updates, see the [Swig Wallet repository](https://github.com/anagrambuild/swig-wallet).

## Search Errors

<div>
  <input type="text" placeholder="Search errors by code, name, or description..." />

  <div />
</div>

## Error Code Ranges

* **1000-1999**: State errors (`swig_state::SwigStateError`)
* **2000-2999**: Instruction processing errors (`swig_instructions::InstructionError`)
* **3000-3999**: Authentication errors (`swig_state::SwigAuthenticateError`)
* **0-999**: Program errors (`swig_program::SwigError`)

## State Errors (`swig_state::SwigStateError`)

Located in: [`state/src/lib.rs:91-108`](https://github.com/anagrambuild/swig-wallet/blob/main/state/src/lib.rs#L91-L108)

These errors are related to state management operations and data validation.

<table>
  <thead>
    <tr>
      <th>Code</th>
      <th>Error</th>
      <th>Description</th>
    </tr>
  </thead>
</table>

## Authentication Errors (`swig_state::SwigAuthenticateError`)

Located in: [`state/src/lib.rs:111-178`](https://github.com/anagrambuild/swig-wallet/blob/main/state/src/lib.rs#L111-L178)

These errors are related to authentication operations and permission validation.

<table>
  <thead>
    <tr>
      <th>Code</th>
      <th>Error</th>
      <th>Description</th>
    </tr>
  </thead>
</table>

## Program Errors (`swig_program::SwigError`)

Located in: [`program/src/error.rs:20-115`](https://github.com/anagrambuild/swig-wallet/blob/main/program/src/error.rs#L20-L115)

These errors can occur during program execution and are categorized by functionality.

<table>
  <thead>
    <tr>
      <th>Code</th>
      <th>Error</th>
      <th>Description</th>
    </tr>
  </thead>
</table>

## Instruction Processing Errors (`swig_instructions::InstructionError`)

Located in: [`instructions/src/lib.rs:25-32`](https://github.com/anagrambuild/swig-wallet/blob/main/instructions/src/lib.rs#L25-L32)

These errors can occur during instruction processing and parsing.

<table>
  <thead>
    <tr>
      <th>Code</th>
      <th>Error</th>
      <th>Description</th>
    </tr>
  </thead>
</table>

## SDK Errors (`rust_sdk::SwigError`)

Located in: [`rust-sdk/src/error.rs:4-80`](https://github.com/anagrambuild/swig-wallet/blob/main/rust-sdk/src/error.rs#L4-L80)

These errors occur in the Rust SDK when interacting with the Swig wallet system.

<table>
  <thead>
    <tr>
      <th>Error</th>
      <th>Description</th>
    </tr>
  </thead>
</table>

## Common Error Patterns

### Permission-Related Errors

Most permission errors start with `PermissionDenied` and are in the 3000+ range. These indicate various authorization failures.

### Data Validation Errors

Errors starting with `Invalid` typically indicate malformed or invalid data structures.

### Account-Related Errors

Errors containing `Account` in the name relate to account validation, ownership, or state issues.

### Signature-Related Errors

Errors containing `Signature` or cryptographic scheme names (like `Secp256k1`, `Secp256r1`) relate to signature validation failures.


# null
Source: https://build.onswig.com/reference/index



# SWIG SDKs: TypeScript and Rust

SWIG provides powerful SDKs in both TypeScript and Rust, each optimized for different use cases in the blockchain development ecosystem. Let's explore how these SDKs can enhance your development experience.

## TypeScript SDK

The TypeScript SDK is specifically designed for frontend applications and wallet integrations. It excels in:

* **Wallet Integration**: Seamlessly connect with web-based wallets and handle user interactions
* **Frontend Development**: Build responsive and interactive dApp interfaces
* **Browser Compatibility**: Optimized for web environments and modern browsers
* **User Experience**: Provides smooth, asynchronous operations for blockchain interactions

Perfect for:

* Web-based dApps
* Wallet interfaces
* User-facing blockchain applications
* Interactive frontend experiences

## Rust SDK

The Rust SDK is engineered for high-performance backend applications and command-line tools. Its strengths include:

* **Server Applications**: Build robust backend services with native performance
* **CLI Tools**: Create powerful command-line interfaces for blockchain interactions
* **Performance**: Leverage Rust's zero-cost abstractions and memory safety
* **System Integration**: Deep integration with system-level resources

Ideal for:

* Backend services
* Command-line tools
* High-performance applications
* System-level blockchain integration

## Choosing the Right SDK

When building your blockchain application:

* Choose the **TypeScript SDK** when you need to:
  * Build user interfaces
  * Integrate with web wallets
  * Create frontend applications
  * Handle user interactions

* Choose the **Rust SDK** when you need to:
  * Develop backend services
  * Create CLI tools
  * Optimize for performance
  * Build system-level applications

Both SDKs provide comprehensive tooling for blockchain development, allowing you to choose the best tool for your specific use case while maintaining full compatibility with the SWIG ecosystem.


# Rust SDK
Source: https://build.onswig.com/reference/rust/index

Typesafe, Memory Safe wallet anyone?

The Rust SDK is a powerful toolkit designed for backend use cases, providing developers with robust tools for blockchain interaction and wallet management. The SDK is built on three main pillars:

## Instruction Builder

The Instruction Builder is a core component that helps developers construct and manage blockchain instructions. It provides a type-safe and intuitive way to build transaction instructions, making it easier to interact with the blockchain while maintaining security and reliability.

Key features:

* Type-safe instruction building
* Transaction composition
* Built-in validation

## Swig Rust Wallet

The Swig Rust Wallet component provides comprehensive wallet management capabilities. It handles key management, transaction signing, and account operations with a focus on security and performance.

Key features:

* Secure key management
* Transaction signing
* Account operations
* Balance tracking

## Swig CLI

The Swig CLI is a command-line interface tool that provides direct access to wallet functionality from the terminal. It's built on top of the Rust SDK and offers a convenient way to interact with the blockchain for testing, development, and automation purposes.

Key features:

* Command-line wallet management
* Transaction creation and signing
* Account information retrieval
* Network interaction utilities

## Code References

The SDK's source code can be found in the following locations:

* [Instruction Builder/Rust Wallet Source](https://github.com/anagrambuild/swig-wallet/tree/main/rust-sdk)
* [Swig CLI Documentation](https://github.com/anagrambuild/swig-wallet/blob/main/cli-x/README.md)
* [Rust SDK Documentation](https://github.com/anagrambuild/swig-wallet/tree/main/docs/rust-sdk)

## Getting Started

To start using the Rust SDK, you'll need to add it as a dependency to your Rust project. The SDK provides a modular architecture allowing you to use only the components you need for your specific use case.

For detailed implementation examples and API documentation, please refer to the individual component documentation linked above.


# Instruction Builder
Source: https://build.onswig.com/reference/rust/instruction_builder

Sometimes you just need to build an instruction

The `SwigInstructionBuilder` is a fundamental component of the Swig SDK that handles the creation and management of Solana instructions for the Swig protocol.

## Overview

The instruction builder provides low-level functionality for creating various types of instructions needed to interact with Swig wallets on the Solana blockchain.

## Core Components

### AuthorityManager

```rust theme={null}
pub enum AuthorityManager {
    Ed25519(Pubkey),
    Secp256k1(Box<[u8]>, Box<dyn Fn(&[u8]) -> [u8; 65]>),
    Ed25519Session(CreateEd25519SessionAuthority),
    Secp256k1Session(CreateSecp256k1SessionAuthority, Box<dyn Fn(&[u8]) -> [u8; 65]>),
}
```

The `AuthorityManager` enum represents different types of signing authorities supported by the Swig protocol.

### SwigInstructionBuilder

```rust theme={null}
pub struct SwigInstructionBuilder {
    swig_id: [u8; 32],
    swig_account: Pubkey,
    authority_manager: AuthorityManager,
    payer: Pubkey,
    role_id: u32,
}
```

## Core Functions

### Creating a New Instance

```rust theme={null}
pub fn new(
    swig_id: [u8; 32],
    authority_manager: AuthorityManager,
    payer: Pubkey,
    role_id: u32,
) -> Self
```

Creates a new instance of the instruction builder with the specified parameters.

### Building a Swig Account

```rust theme={null}
pub fn build_swig_account(&self) -> Result<Instruction, SwigError>
```

Creates an instruction to initialize a new Swig account on-chain.

### Signing Instructions

```rust theme={null}
pub fn sign_instruction(
    &mut self,
    instructions: Vec<Instruction>,
    current_slot: Option<u64>,
) -> Result<Vec<Instruction>, SwigError>
```

Creates signed instructions for the provided transaction instructions.

## Authority Management

### Adding Authorities

```rust theme={null}
pub fn add_authority_instruction(
    &mut self,
    new_authority_type: AuthorityType,
    new_authority: &[u8],
    permissions: Vec<ClientPermission>,
    current_slot: Option<u64>,
) -> Result<Instruction, SwigError>
```

Creates an instruction to add a new authority with specified permissions.

### Removing Authorities

```rust theme={null}
pub fn remove_authority(
    &mut self,
    authority_to_remove_id: u32,
    current_slot: Option<u64>,
) -> Result<Instruction, SwigError>
```

Creates an instruction to remove an existing authority.

### Replacing Authorities

```rust theme={null}
pub fn replace_authority(
    &mut self,
    authority_to_replace_id: u32,
    new_authority_type: AuthorityType,
    new_authority: &[u8],
    permissions: Vec<ClientPermission>,
    current_slot: Option<u64>,
) -> Result<Vec<Instruction>, SwigError>
```

Creates instructions to replace an existing authority with a new one.

## Session Management

### Creating Sessions

```rust theme={null}
pub fn create_session_instruction(
    &self,
    session_key: Pubkey,
    session_duration: u64,
    current_slot: Option<u64>,
) -> Result<Instruction, SwigError>
```

Creates an instruction to create a new session for temporary authority delegation.

## Utility Functions

### Getting the Swig Account

```rust theme={null}
pub fn get_swig_account(&self) -> Result<Pubkey, SwigError>
```

Returns the public key of the Swig account.

### Getting the Role ID

```rust theme={null}
pub fn get_role_id(&self) -> u32
```

Returns the current role ID of the Swig account.

### Switching Authority

```rust theme={null}
pub fn switch_authority(&mut self, role_id: u32, authority: Pubkey) -> Result<(), SwigError>
```

Switches the current authority and role ID.

## Examples

### Creating a New Swig Account

```rust theme={null}
let instruction_builder = SwigInstructionBuilder::new(
    swig_id,
    AuthorityManager::Ed25519(authority_pubkey),
    payer_pubkey,
    0
);

let create_ix = instruction_builder.build_swig_account()?;
```

### Adding a New Authority

```rust theme={null}
let add_authority_ix = instruction_builder.add_authority_instruction(
    AuthorityType::Ed25519,
    new_authority_bytes,
    vec![Permission::All],
    Some(current_slot)
)?;
```


# Rust Wallet
Source: https://build.onswig.com/reference/rust/rust_wallet

A iron wallet, with a little rust

The `SwigWallet` is an abstraction for interacting with Swig wallets on chain. It provides a user-friendly interface for managing wallets, authorities, and transactions.

## Overview

The Wallet SDK builds upon the instruction builder to provide comprehensive Swig wallet management. It handles RPC communication, transaction building, and wallet state management.

## Core Components

### SwigWallet Structure

```rust theme={null}
pub struct SwigWallet<'a> {
    instruction_builder: SwigInstructionBuilder,
    rpc_client: RpcClient,
    fee_payer: &'a Keypair,
    authority: &'a Keypair,
}
```

## Core Functions

### Creating a New Wallet

```rust theme={null}
pub fn new(
    swig_id: [u8; 32],
    authority_manager: AuthorityManager,
    fee_payer: &'c Keypair,
    authority: &'c Keypair,
    rpc_url: String,
) -> Result<Self, SwigError>
```

Creates a new Swig wallet or initializes an existing one.

## Authority Management

### Adding Authorities

```rust theme={null}
pub fn add_authority(
    &mut self,
    new_authority_type: AuthorityType,
    new_authority: &[u8],
    permissions: Vec<Permission>,
) -> Result<Signature, SwigError>
```

Adds a new authority to the wallet with specified permissions.

### Removing Authorities

```rust theme={null}
pub fn remove_authority(
    &mut self,
    authority: &[u8]
) -> Result<Signature, SwigError>
```

Removes an existing authority from the wallet.

### Replacing Authorities

```rust theme={null}
pub fn replace_authority(
    &mut self,
    authority_to_replace_id: u32,
    new_authority_type: AuthorityType,
    new_authority: &[u8],
    permissions: Vec<Permission>,
) -> Result<Signature, SwigError>
```

Replaces an existing authority with a new one.

## Transaction Management

### Signing Transactions

```rust theme={null}
pub fn sign(
    &mut self,
    inner_instructions: Vec<Instruction>,
    alt: Option<&[AddressLookupTableAccount]>,
) -> Result<Signature, SwigError>
```

Signs and sends a transaction containing the provided instructions.

## Session Management

### Creating Sessions

```rust theme={null}
pub fn create_session(
    &mut self,
    session_key: Pubkey,
    duration: u64
) -> Result<(), SwigError>
```

Creates a new session for temporary authority delegation.

## Wallet Information

### Displaying Wallet Details

```rust theme={null}
pub fn display_swig(&self) -> Result<(), SwigError>
```

Displays detailed information about the wallet, including:

* Account address
* Total roles
* Balance
* Authority details
* Permissions

### Getting Wallet Balance

```rust theme={null}
pub fn get_balance(&self) -> Result<u64, SwigError>
```

Returns the SOL balance of the Swig account.

### Getting Authority Permissions

```rust theme={null}
pub fn get_current_authority_permissions(&self) -> Result<Vec<Permission>, SwigError>
```

Retrieves the current authority's permissions from the Swig account.

## Utility Functions

### Switching Authority

```rust theme={null}
pub fn switch_authority(
    &mut self,
    role_id: u32,
    authority: Pubkey
) -> Result<(), SwigError>
```

Switches to a different authority for the wallet.

### Switching Fee Payer

```rust theme={null}
pub fn switch_payer(
    &mut self,
    payer: &'c Keypair
) -> Result<(), SwigError>
```

Updates the fee payer for the wallet.

## Examples

### Creating a New Wallet

```rust theme={null}
let wallet = SwigWallet::new(
    swig_id,
    AuthorityManager::Ed25519(authority_pubkey),
    &fee_payer,
    &authority,
    "https://api.mainnet-beta.solana.com".to_string(),
)?;
```

### Adding an Authority with Permissions

```rust theme={null}
let signature = wallet.add_authority(
    AuthorityType::Ed25519,
    &new_authority_bytes,
    vec![
        Permission::All,
        Permission::Sol {
            amount: 1_000_000_000, // 1 SOL
            recurring: None,
        },
    ],
)?;
```

### Creating a Session

```rust theme={null}
wallet.create_session(
    session_keypair.pubkey(),
    1000, // Duration in slots
)?;
```

### Signing a Transaction

```rust theme={null}
let signature = wallet.sign(
    vec![transfer_instruction],
    None, // No address lookup tables
)?;
```


# null
Source: https://build.onswig.com/reference/typescript/actions



# Swig Actions Documentation

This document provides comprehensive documentation for all available Swig Actions, including their inputs, outputs, and usage examples.

## Overview

Swig Actions define permissions and spending limits for authorities in the Swig wallet system. Actions are composed using a builder pattern starting with `Actions.set()` and ending with `.get()`.

```typescript theme={null}
const actions = Actions.set()
  .tokenDestinationLimit({
    mint: mintKeypair.publicKey,
    amount: tokenLimitAmount,
    destination: recipientAta,
  })
  .get();
```

## Action Categories

### 1. Root/Management Actions

#### `all()`

Grants unlimited permissions for all operations.

**Inputs:** None\
**Output:** `Actions` instance

**Usage:**

```typescript theme={null}
const rootActions = Actions.set().all().get();
```

**Permissions Granted:**

* Unlimited SOL and token spending
* Access to all programs
* Authority management
* All other operations

***

#### `manageAuthority()`

Grants permission to manage authorities (add/remove authorities).

**Inputs:** None\
**Output:** `Actions` instance

**Usage:**

```typescript theme={null}
const manageActions = Actions.set().manageAuthority().get();
```

**Permissions Granted:**

* Add new authorities
* Remove existing authorities

***

#### `allButManageAuthority()`

Grants all permissions except authority management.

**Inputs:** None\
**Output:** `Actions` instance

**Usage:**

```typescript theme={null}
const limitedRootActions = Actions.set().allButManageAuthority().get();
```

**Permissions Granted:**

* Unlimited SOL and token spending
* Access to all programs
* All operations except authority management

***

### 2. Program Actions

#### `programLimit(payload)`

Grants permission to interact with a specific program.

**Inputs:**

* `payload.programId: SolPublicKeyData` - The program ID to allow access to

**Output:** `Actions` instance

**Usage:**

```typescript theme={null}
const programActions = Actions.set()
  .programLimit({ programId: 'SystemProgram11111111111111111111111111111' })
  .get();
```

**Permissions Granted:**

* Execute transactions with the specified program

***

#### `programAll()`

Grants permission to interact with all programs.

**Inputs:** None\
**Output:** `Actions` instance

**Usage:**

```typescript theme={null}
const allProgramActions = Actions.set().programAll().get();
```

**Permissions Granted:**

* Execute transactions with any program

***

#### `programCurated()`

Grants permission to interact with curated/whitelisted programs.

**Inputs:** None\
**Output:** `Actions` instance

**Usage:**

```typescript theme={null}
const curatedActions = Actions.set().programCurated().get();
```

**Permissions Granted:**

* Execute transactions with approved/curated programs

***

#### `programScopeBasic(payload)`

Basic program scope with specific target account.

**Inputs:**

* `payload.programId: SolPublicKeyData` - Program ID
* `payload.targetAccount: SolPublicKeyData` - Target account within the program

**Output:** `Actions` instance

**Usage:**

```typescript theme={null}
const basicScopeActions = Actions.set()
  .programScopeBasic({
    programId: 'TokenProgramId',
    targetAccount: 'TokenAccountAddress',
  })
  .get();
```

**Permissions Granted:**

* Access to specific program with targeted account interactions

***

#### `programScopeLimit(payload)`

Program scope with spending limits.

**Inputs:**

* `payload.programId: SolPublicKeyData` - Program ID
* `payload.targetAccount: SolPublicKeyData` - Target account
* `payload.amount: bigint` - Maximum spendable amount
* `payload.numericType: NumericType` - Numeric type (U8, U32, U64, U128)

**Output:** `Actions` instance

**Usage:**

```typescript theme={null}
import { NumericType } from '@swig-wallet/coder';

const limitedScopeActions = Actions.set()
  .programScopeLimit({
    programId: 'TokenProgramId',
    targetAccount: 'TokenAccountAddress',
    amount: 1000n,
    numericType: NumericType.U64,
  })
  .get();
```

**Permissions Granted:**

* Limited access to specific program with amount restrictions

***

#### `programScopeRecurringLimit(payload)`

Program scope with recurring spending limits.

**Inputs:**

* `payload.programId: SolPublicKeyData` - Program ID
* `payload.targetAccount: SolPublicKeyData` - Target account
* `payload.amount: bigint` - Recurring amount limit
* `payload.window: bigint` - Time window in slots for limit reset
* `payload.numericType: NumericType` - Numeric type (U8, U32, U64, U128)

**Output:** `Actions` instance

**Usage:**

```typescript theme={null}
const recurringLimitActions = Actions.set()
  .programScopeRecurringLimit({
    programId: 'TokenProgramId',
    targetAccount: 'TokenAccountAddress',
    amount: 1000n,
    window: 1000n, // slots
    numericType: NumericType.U64,
  })
  .get();
```

**Permissions Granted:**

* Recurring limited access to specific program

***

### 3. SOL Spending Actions

#### `solLimit(payload)`

One-time SOL spending limit.

**Inputs:**

* `payload.amount: bigint` - Maximum SOL amount to spend (in lamports)

**Output:** `Actions` instance

**Usage:**

```typescript theme={null}
const solActions = Actions.set()
  .solLimit({ amount: 1000000000n }) // 1 SOL in lamports
  .get();
```

**Permissions Granted:**

* Spend up to the specified amount of SOL once

***

#### `solRecurringLimit(payload)`

Recurring SOL spending limit.

**Inputs:**

* `payload.recurringAmount: bigint` - SOL amount per window (in lamports)
* `payload.window: bigint` - Time window in slots until reset

**Output:** `Actions` instance

**Usage:**

```typescript theme={null}
const recurringActions = Actions.set()
  .solRecurringLimit({
    recurringAmount: 500000000n, // 0.5 SOL per window
    window: 100000n, // slots
  })
  .get();
```

**Permissions Granted:**

* Spend up to the specified amount of SOL per time window

***

#### `solDestinationLimit(payload)`

One-time SOL spending to a specific destination.

**Inputs:**

* `payload.amount: bigint` - SOL amount (in lamports)
* `payload.destination: SolPublicKeyData` - Destination public key

**Output:** `Actions` instance

**Usage:**

```typescript theme={null}
const destinationActions = Actions.set()
  .solDestinationLimit({
    amount: 2000000000n, // 2 SOL
    destination: 'RecipientPublicKey',
  })
  .get();
```

**Permissions Granted:**

* Send up to the specified SOL amount to the specified destination once

***

#### `solRecurringDestinationLimit(payload)`

Recurring SOL spending to a specific destination.

**Inputs:**

* `payload.recurringAmount: bigint` - SOL amount per window (in lamports)
* `payload.window: bigint` - Time window in slots until reset
* `payload.destination: SolPublicKeyData` - Destination public key

**Output:** `Actions` instance

**Usage:**

```typescript theme={null}
const recurringDestActions = Actions.set()
  .solRecurringDestinationLimit({
    recurringAmount: 1000000000n, // 1 SOL per window
    window: 86400n, // slots (approximately 1 day)
    destination: 'RecipientPublicKey',
  })
  .get();
```

**Permissions Granted:**

* Send up to the specified SOL amount to the destination per time window

***

### 4. Token Spending Actions

#### `tokenLimit(payload)`

One-time token spending limit.

**Inputs:**

* `payload.mint: SolPublicKeyData` - Token mint public key
* `payload.amount: bigint` - Maximum token amount to spend

**Output:** `Actions` instance

**Usage:**

```typescript theme={null}
const tokenActions = Actions.set()
  .tokenLimit({
    mint: 'USDCMintPublicKey',
    amount: 1000000n, // 1 USDC (6 decimals)
  })
  .get();
```

**Permissions Granted:**

* Spend up to the specified amount of the token once

***

#### `tokenRecurringLimit(payload)`

Recurring token spending limit.

**Inputs:**

* `payload.mint: SolPublicKeyData` - Token mint public key
* `payload.recurringAmount: bigint` - Token amount per window
* `payload.window: bigint` - Time window in slots until reset

**Output:** `Actions` instance

**Usage:**

```typescript theme={null}
const recurringTokenActions = Actions.set()
  .tokenRecurringLimit({
    mint: 'USDCMintPublicKey',
    recurringAmount: 500000n, // 0.5 USDC per window
    window: 50000n, // slots
  })
  .get();
```

**Permissions Granted:**

* Spend up to the specified token amount per time window

***

#### `tokenDestinationLimit(payload)`

One-time token spending to a specific destination.

**Inputs:**

* `payload.mint: SolPublicKeyData` - Token mint public key
* `payload.amount: bigint` - Token amount
* `payload.destination: SolPublicKeyData` - Destination public key

**Output:** `Actions` instance

**Usage:**

```typescript theme={null}
const tokenDestActions = Actions.set()
  .tokenDestinationLimit({
    mint: 'USDCMintPublicKey',
    amount: 2000000n, // 2 USDC
    destination: 'RecipientTokenAccount',
  })
  .get();
```

**Permissions Granted:**

* Send up to the specified token amount to the destination once

***

#### `tokenRecurringDestinationLimit(payload)`

Recurring token spending to a specific destination.

**Inputs:**

* `payload.mint: SolPublicKeyData` - Token mint public key
* `payload.recurringAmount: bigint` - Token amount per window
* `payload.window: bigint` - Time window in slots until reset
* `payload.destination: SolPublicKeyData` - Destination public key

**Output:** `Actions` instance

**Usage:**

```typescript theme={null}
const recurringTokenDestActions = Actions.set()
  .tokenRecurringDestinationLimit({
    mint: 'USDCMintPublicKey',
    recurringAmount: 1000000n, // 1 USDC per window
    window: 86400n, // slots
    destination: 'RecipientTokenAccount',
  })
  .get();
```

**Permissions Granted:**

* Send up to the specified token amount to the destination per time window

***

### 5. Staking Actions

#### `stakeAll()`

Unlimited staking permissions.

**Inputs:** None\
**Output:** `Actions` instance

**Usage:**

```typescript theme={null}
const stakeActions = Actions.set().stakeAll().get();
```

**Permissions Granted:**

* Unlimited staking operations

***

#### `stakeLimit(payload)`

One-time staking limit.

**Inputs:**

* `payload.amount: bigint` - Maximum stake amount

**Output:** `Actions` instance

**Usage:**

```typescript theme={null}
const stakeLimitActions = Actions.set()
  .stakeLimit({ amount: 5000000000n }) // 5 SOL
  .get();
```

**Permissions Granted:**

* Stake up to the specified amount once

***

#### `stakeRecurringLimit(payload)`

Recurring staking limit.

**Inputs:**

* `payload.recurringAmount: bigint` - Stake amount per window
* `payload.window: bigint` - Time window in slots until reset

**Output:** `Actions` instance

**Usage:**

```typescript theme={null}
const recurringStakeActions = Actions.set()
  .stakeRecurringLimit({
    recurringAmount: 1000000000n, // 1 SOL per window
    window: 100000n, // slots
  })
  .get();
```

**Permissions Granted:**

* Stake up to the specified amount per time window

***

### 6. Account Management Actions

#### `subAccount()`

Grants permission to control a subaccount.

**Inputs:** None\
**Output:** `Actions` instance

**Usage:**

```typescript theme={null}
const subAccountActions = Actions.set().subAccount().get();
```

**Permissions Granted:**

* Control and manage subaccount operations

***

## Action Types Reference

### `SolPublicKeyData`

A Solana public key in various formats:

* String (base58)
* Uint8Array (32 bytes)
* PublicKey object

### `NumericType`

Enum defining numeric types:

```typescript theme={null}
enum NumericType {
  U8, // 8-bit unsigned integer
  U32, // 32-bit unsigned integer
  U64, // 64-bit unsigned integer
  U128, // 128-bit unsigned integer
}
```

## Combining Actions

Actions can be chained together to create complex permission sets:

```typescript theme={null}
const complexActions = Actions.set()
  .programAll() // Allow all programs
  .solLimit({ amount: 1000000000n }) // 1 SOL spending limit
  .tokenLimit({
    // Token spending limit
    mint: 'USDCMintPublicKey',
    amount: 1000000n,
  })
  .tokenDestinationLimit({
    // Specific destination limit
    mint: 'USDTMintPublicKey',
    amount: 500000n,
    destination: 'RecipientAccount',
  })
  .get();
```

## Return Value: Actions Object

The `.get()` method returns an `Actions` object with the following methods:

### Query Methods

* `count: number` - Number of actions
* `bytes(): Uint8Array` - Serialized action bytes
* `isRoot(): boolean` - Check if root action present
* `canManageAuthority(): boolean` - Check authority management permission
* `canUseProgram(programId): boolean` - Check program access permission
* `hasProgramAction(): boolean` - Check if any program action exists

### SOL Spending Methods

* `canSpendSol(amount?): boolean` - Check SOL spending permission
* `canSpendSolMax(): boolean` - Check unlimited SOL spending
* `solSpendLimit(): bigint | null` - Get SOL spending limit (null = unlimited)
* `solSpend(): SpendController` - Get SOL spend controller

### Token Spending Methods

* `canSpendToken(mint, amount?): boolean` - Check token spending permission
* `canSpendTokenMax(mint): boolean` - Check unlimited token spending
* `tokenSpendLimit(mint): bigint | null` - Get token spending limit
* `tokenSpend(mint): SpendController` - Get token spend controller

## Usage Examples

### Simple Token Limit

```typescript theme={null}
const actions = Actions.set()
  .tokenLimit({
    mint: mintKeypair.publicKey,
    amount: 1000000n,
  })
  .get();

// Check if can spend 500000 tokens
if (actions.canSpendToken(mintKeypair.publicKey, 500000n)) {
  console.log('Can spend tokens');
}
```

### Program + Destination Limits

```typescript theme={null}
const actions = Actions.set()
  .programAll()
  .solDestinationLimit({
    destination: recipientAddress,
    amount: 500000000n, // 0.5 SOL
  })
  .get();

console.log('Actions count:', actions.count); // 2
console.log('Can use programs:', actions.hasProgramAction()); // true
console.log('Can spend SOL:', actions.canSpendSol()); // true
```

### Recurring Subscription Pattern

```typescript theme={null}
const subscriptionActions = Actions.set()
  .tokenRecurringDestinationLimit({
    mint: usdcMint,
    recurringAmount: 10000000n, // 10 USDC per month
    window: 2160000n, // ~30 days in slots
    destination: serviceProvider,
  })
  .programLimit({ programId: tokenProgramId })
  .get();
```

This comprehensive documentation covers all available Swig Actions with their inputs, outputs, and practical usage examples.


# Swig TypeScript SDK
Source: https://build.onswig.com/reference/typescript/index

The Swig TypeScript SDK provides a robust interface for interacting with Solana smart contracts and wallets.

The Swig TypeScript SDK provides a robust interface for interacting with Solana smart contracts and wallets. Built on top of the Web3.js 1.0 line of Solana SDK, it offers developers a streamlined experience for building decentralized applications on Solana.

## Architecture Overview

The v1.0 SDK has been completely refactored with a modular architecture:

* **`@swig-wallet/coder`** - Low-level encoding/decoding utilities
* **`@swig-wallet/lib`** - Core functionality
* **`@swig-wallet/classic`** - High-level wrapper functions for Web3.js 1.x compatibility
* **`@swig-wallet/kit`** - High-level wrapper functions for Web3.js 2.0 (Solana Kit) compatibility

## API Reference

The canonical source for the Swig TypeScript SDK API documentation can be found at:
[https://anagrambuild.github.io/swig-ts/modules.html](https://anagrambuild.github.io/swig-ts/modules.html)

### Key Packages

#### `@swig-wallet/classic`

For Web3.js 1.x applications, providing:

* Instruction builders returning `TransactionInstruction[]`
* Account fetching utilities using `Connection`
* PDA derivation functions (synchronous)
* Re-exports of core functionality from `@swig-wallet/lib`

#### `@swig-wallet/kit`

For Web3.js 2.0 (Solana Kit) applications, providing:

* Instruction builders returning `KitInstruction[]`
* Account fetching utilities using `Rpc<GetAccountInfoApi>`
* PDA derivation functions (asynchronous)
* Same API surface as classic but with Web3.js 2.0 types

#### `@swig-wallet/lib`

Core logic including:

* `Actions` class for permission management
* `Swig` class for wallet representation
* Authority management utilities
* Instruction context builders

#### `@swig-wallet/coder`

Low-level utilities for:

* Account data encoding/decoding
* Instruction data serialization
* Type definitions

## Migration from Beta Versions

**Breaking Changes in v1.0:**

* Complete API restructure - most function signatures have changed
* Functions now return `TransactionInstruction[]` instead of single instructions
* Authority and Actions classes moved to `@swig-wallet/lib`
* New dependency on `@solana-program/token` instead of `@solana/spl-token`

## Web3.js Version Support

The Swig SDK supports both major versions of the Solana Web3.js library:

### Web3.js 1.x (`@swig-wallet/classic`)

* Uses `Connection`, `PublicKey`, `TransactionInstruction`
* Synchronous PDA derivation
* Compatible with existing Web3.js 1.x applications
* Stable and production-ready

### Web3.js 2.0 (`@swig-wallet/kit`)

* Uses `Rpc`, `Address`, `KitInstruction`
* Asynchronous PDA derivation
* Built for the new Solana Kit architecture
* Future-ready with enhanced type safety

## V2 Protocol Features

The SDK now supports both v1 and v2 Swig accounts with automatic version detection:

### Automatic Version Detection

```typescript theme={null}
const swig = await fetchSwigAccount(swigAddress);
const version = swig.accountVersion(); // 'v1' | 'v2'
const walletAddress = await getSwigWalletAddress(swig); // Auto-resolves correct address
```

### Enhanced Account Structure

* **V1 Accounts**: Traditional structure with rent exempt lamports
* **V2 Accounts**: Optimized structure using PDA bump seeds and system-derived wallet addresses

### SignV2 Instruction

New instruction type optimized for v2 accounts with automatic selection based on account version.

### Program Action Management

Automatic program permission handling with `ensureProgramAction` for streamlined authority management.

## Future Development

We are actively working on expanding the SDK's capabilities. Recent v2 improvements include:

* ✅ Automatic version detection and handling
* ✅ Enhanced account structure with PDA-based addressing
* ✅ SignV2 instruction for improved performance
* ✅ Automatic program action management

Upcoming features include:

* Enhanced session management
* Additional authority types
* Integration with Gill
* Performance optimizations

These additions will provide developers with even more flexibility and enhanced capabilities for building on Solana.

Stay tuned for updates as we continue to evolve the SDK to meet the growing needs of the Solana development community.


# Swig Kit Package (Web3.js 2.0)
Source: https://build.onswig.com/reference/typescript/kit

Using Swig with Web3.js 2.0 (Solana Kit)

The `@swig-wallet/kit` package provides the same functionality as `@swig-wallet/classic` but is designed specifically for Web3.js 2.0 (Solana Kit) applications.

## Installation

```bash theme={null}
npm install @swig-wallet/kit @solana/kit @solana-program/token
```

## Key Differences from Classic

### Type System

* Uses `Address` instead of `PublicKey`
* Uses `KitInstruction` instead of `TransactionInstruction`
* Uses `Rpc<GetAccountInfoApi>` instead of `Connection`

### Asynchronous PDA Derivation

```typescript theme={null}
// Classic (synchronous)
const swigAddress = findSwigPda(id);

// Kit (asynchronous)
const swigAddress = await findSwigPda(id);
```

### Account Fetching

```typescript theme={null}
// Classic
import { Connection } from "@solana/web3.js";
const connection = new Connection("https://api.mainnet-beta.solana.com");
const swig = await fetchSwig(connection, swigAddress);

// Kit
import { createSolanaRpc } from "@solana/kit";
const rpc = createSolanaRpc("https://api.mainnet-beta.solana.com");
const swig = await fetchSwig(rpc, swigAddress);
```

## Basic Usage

### Creating a Swig

```typescript theme={null}
import { createSolanaRpc, generateKeyPair } from "@solana/kit";
import {
  Actions,
  getCreateSwigInstruction,
  findSwigPda,
  createEd25519AuthorityInfo,
} from "@swig-wallet/kit";

const rpc = createSolanaRpc("https://api.devnet.solana.com");
const user = await generateKeyPair();

// Generate unique ID
const id = new Uint8Array(32);
crypto.getRandomValues(id);

// Derive Swig address (async in kit)
const swigAddress = await findSwigPda(id);

// Create authority info
const rootAuthorityInfo = createEd25519AuthorityInfo(user.address);

// Create actions
const rootActions = Actions.set().manageAuthority().get();

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

// Build and send transaction (using Web3.js 2.0 patterns)
// ... transaction building code
```

### Adding Authorities

```typescript theme={null}
import { fetchSwig, getAddAuthorityInstructions } from "@swig-wallet/kit";

// Fetch the Swig account
const swig = await fetchSwig(rpc, swigAddress);

// Find the root role
const rootRole = swig.findRolesByEd25519SignerPk(rootUser.address)[0];

// Create new authority
const newAuthorityInfo = createEd25519AuthorityInfo(newAuthority.address);
const actions = Actions.set()
  .solLimit({ amount: BigInt(1000000000) })
  .get();

// Get add authority instructions
const addAuthorityInstructions = await getAddAuthorityInstructions(
  swig,
  rootRole.id,
  newAuthorityInfo,
  actions,
);

// Build transaction with instructions
// ... transaction building code
```

### Signing Instructions

```typescript theme={null}
import { getSignInstructions } from "@swig-wallet/kit";

// Create the instruction to be signed
const transferIx = createTransferInstruction({
  source: sourceTokenAccount,
  destination: destinationTokenAccount,
  owner: swigAddress,
  amount: BigInt(1000000),
});

// Get signing instructions
const signedInstructions = await getSignInstructions(swig, roleId, [
  transferIx,
]);

// Build transaction
// ... transaction building code
```

## API Reference

### Account Functions

* `fetchSwig(rpc, address, config?)` - Fetch a Swig account
* `fetchMaybeSwigAccount(rpc, address, config?)` - Fetch account or null
* `fetchNullableSwig(rpc, address, config?)` - Fetch Swig or null

### PDA Functions

* `findSwigPda(id)` - Derive Swig PDA (async)
* `findSwigSubAccountPda(swigId, roleId)` - Derive SubAccount PDA (async)

### Instruction Functions

* `getCreateSwigInstruction(args)` - Create Swig instruction
* `getAddAuthorityInstructions(swig, roleId, authorityInfo, actions, options?)` - Add authority
* `getRemoveAuthorityInstructions(swig, roleId, roleToRemoveId, options?)` - Remove authority
* `getSignInstructions(swig, roleId, instructions, withSubAccount?, options?)` - Sign instructions
* `getCreateSessionInstructions(swig, roleId, sessionKey, duration?, options?)` - Create session
* `getCreateSubAccountInstructions(swig, roleId, options?)` - Create sub-account
* `getToggleSubAccountInstructions(swig, roleId, enabled, options?)` - Toggle sub-account
* `getWithdrawFromSubAccountSubAccountInstructions(swig, roleId, withdrawArgs, options?)` - Withdraw from sub-account

## Migration from Classic

The API surface is identical between `@swig-wallet/classic` and `@swig-wallet/kit`, with only type differences:

```typescript theme={null}
// Classic
import { ... } from '@swig-wallet/classic';

// Kit
import { ... } from '@swig-wallet/kit';
```

Key changes when migrating:

1. Replace `Connection` with `Rpc<GetAccountInfoApi>`
2. Replace `PublicKey` with `Address`
3. Replace `TransactionInstruction` with `KitInstruction`
4. Make PDA derivation calls async (`await findSwigPda(id)`)
5. Update transaction building to use Web3.js 2.0 patterns

## Benefits of Web3.js 2.0

* **Enhanced Type Safety**: Better TypeScript support with stricter types
* **Improved Performance**: More efficient RPC handling
* **Modern Architecture**: Built for the future of Solana development
* **Better Error Handling**: More descriptive error messages and handling

## When to Use Kit vs Classic

### Use `@swig-wallet/kit` when:

* Building new applications
* Want the latest Web3.js features
* Need enhanced type safety
* Planning for long-term maintenance

### Use `@swig-wallet/classic` when:

* Working with existing Web3.js 1.x codebases
* Need immediate compatibility
* Have dependencies that require Web3.js 1.x
* Want proven stability

Both packages are actively maintained and provide the same Swig functionality.


# Build an Embedded Wallet with Swig and Para
Source: https://build.onswig.com/tutorials/embeded_wallet_para/index

"The best wallet is the one your users don't even know they're using" - Web3 UX Manifesto

Welcome to the Para Embedded Wallet tutorial! This guide will walk you through setting up a Swig account with Para's solution for embedded wallets. Para provides a modal that makes authentication simple and easy for both developers and users.

## What You'll Learn

In this tutorial, you'll learn how to:

* Set up a Para developer account
* Create a React + Vite project with Para integration
* Implement Para's authentication modal
* Create a Swig account using the Para-generated wallet

## Live Demos

* [Para Modal Example](https://para-modal-example-git-main-anagram.vercel.app/)
* [In App Wallet Example](https://in-app-wallet-example.vercel.app/)

## Time Commitment

This tutorial is designed to be completed in approximately 45 minutes.

## Prerequisites

Before starting this tutorial:

1. Set up a Para account on their [developer portal](https://developer.getpara.com)
2. Generate an API Key
3. Enable Solana as a supported network

## Tutorial Sections

1. Project Setup
2. Para SDK Integration
3. Creating the UI Components
4. Implementing Swig Account Creation

## 1. Project Setup

First, let's create a new Vite project and install the necessary dependencies.

### Create a Vite Project

Follow the [Vite docs](https://vite.dev/guide) to create a new project.

### Install Dependencies

```bash theme={null}
yarn add @getpara/react-sdk @tanstack/react-query @getpara/solana-web3.js-v1-integration @solana/web3.js @swig-wallet/classic @swig-wallet/coder
```

### Set up Vite Polyfills

Install the polyfills package:

```bash theme={null}
yarn add vite-plugin-node-polyfills -D
```

Create or update your `vite.config.ts`:

```typescript theme={null}
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import { nodePolyfills } from "vite-plugin-node-polyfills";
import path from "path";

export default defineConfig({
  plugins: [react(), nodePolyfills()],
  resolve: {
    alias: {
      "@": path.resolve(__dirname, "./src"),
    },
  },
});
```

## 2. Para SDK Integration

### Set up the Para Provider

Create a file called `providers.tsx` in your `src` directory:

```typescript theme={null}
import React from "react";
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { Environment, ParaProvider } from "@getpara/react-sdk";
import "@getpara/react-sdk/styles.css";

const queryClient = new QueryClient();

interface ProvidersProps {
  children: React.ReactNode;
}

export function Providers({ children }: ProvidersProps) {
  return (
    <QueryClientProvider client={queryClient}>
      <ParaProvider
        paraClientConfig={{
          apiKey: import.meta.env.VITE_PARA_API_KEY || "",
          env: Environment.BETA,
        }}
      >
        {children}
      </ParaProvider>
    </QueryClientProvider>
  );
}
```

### Add TypeScript Environment Types

Create a file called `vite-env-d.ts` in your `src` directory:

```typescript theme={null}
/// <reference types="vite/client" />
```

### Configure Environment Variables

Create a `.env.local` file in your project root:

```env theme={null}
VITE_PARA_API_KEY=<your_api_key>
```

> 🔒 Never commit your API key to version control!

## 3. Creating the UI Components

### Update App Component

Modify your `App.tsx`:

```typescript theme={null}
import React from "react";
import { Providers } from "./providers";
import { AppContent } from "./components/AppContent";

const App = () => {
  return (
    <Providers>
      <AppContent />
    </Providers>
  );
};

export default App;
```

### Create the Main Component

Create `AppContent.tsx` in `src/components/`:

```typescript theme={null}
import React, { useState, useEffect } from "react";
import { useAccount, useWallet, useClient } from "@getpara/react-sdk";
import { ParaSolanaWeb3Signer } from "@getpara/solana-web3.js-v1-integration";
import { Connection, LAMPORTS_PER_SOL, PublicKey, Transaction } from "@solana/web3.js";
import { Actions, Swig, findSwigPda, createEd25519AuthorityInfo } from "@swig-wallet/classic";
import { LoginButton } from "./LoginButton";

export const AppContent: React.FC = () => {
  const { data: account } = useAccount();
  const { data: wallet } = useWallet();
  const [swigAddress, setSwigAddress] = useState<string | null>(null);
  const [solBalance, setSolBalance] = useState<number | null>(null);
  const [isCreatingSwig, setIsCreatingSwig] = useState(false);

  const para = useClient();
  const connection = new Connection("https://api.devnet.solana.com");

  const createSwigAccount = async () => {
    if (!wallet?.address || !para) return;
    setIsCreatingSwig(true);

    try {
      // Generate random ID for the Swig account
      const id = new Uint8Array(32);
      crypto.getRandomValues(id);

      const paraPubkey = new PublicKey(wallet.address);
      const [swigPdaAddress] = findSwigPda(id);

      // Create Para Solana signer
      const signer = new ParaSolanaWeb3Signer(para, connection, wallet.id);

      // Create root authority info
      const rootAuthorityInfo = createEd25519AuthorityInfo(paraPubkey);

      // Set up actions
      const rootActions = Actions.set().all().get();

      // Create the Swig creation instruction
      const createSwigInstruction = Swig.create({
        authorityInfo: rootAuthorityInfo,
        id,
        payer: paraPubkey,
        actions: rootActions,
      });

      // Build transaction
      const transaction = new Transaction();
      transaction.add(createSwigInstruction);
      transaction.feePayer = paraPubkey;

      // Get recent blockhash
      const { blockhash } = await connection.getLatestBlockhash();
      transaction.recentBlockhash = blockhash;

      // Sign transaction using Para's Solana signer
      const signedTransaction = await signer.signTransaction(transaction);

      // Send the signed transaction
      const signature = await connection.sendRawTransaction(signedTransaction.serialize());

      // Wait for confirmation
      await connection.confirmTransaction({
        signature,
        blockhash,
        lastValidBlockHeight: (await connection.getLatestBlockhash()).lastValidBlockHeight,
      });

      setSwigAddress(swigPdaAddress.toBase58());
      setIsCreatingSwig(false);

      console.log("Swig account created successfully!");
      console.log("Swig address:", swigPdaAddress.toBase58());
      console.log("Transaction signature:", signature);
    } catch (error) {
      console.error("Error in transaction signing:", error);
      setIsCreatingSwig(false);
    }
  };

  useEffect(() => {
    const fetchBalance = async () => {
      if (wallet?.address) {
        try {
          const balance = await connection.getBalance(new PublicKey(wallet.address));
          setSolBalance(balance / LAMPORTS_PER_SOL);
        } catch (e) {
          setSolBalance(null);
        }
      }
    };
    fetchBalance();
  }, [wallet?.address]);

  return (
    <div className="min-h-screen flex justify-center p-4">
      <div className="max-w-md w-full space-y-6 p-8">
        <div className="text-center">
          <h2 className="text-3xl font-extrabold text-gray-900">Para Solana Web3.js Example</h2>
          <p className="mt-2 text-sm text-gray-600">
            Using Para's Solana Web3.js integration for transaction signing
          </p>
        </div>
        {account?.isConnected && wallet && (
          <div className="text-center mb-4">
            <p className="text-green-700 font-medium">You are signed in!</p>
            <p className="text-sm text-gray-700">
              Wallet address:{" "}
              <span className="font-mono break-all">
                {para
                  ? para.getDisplayAddress(wallet.id, { truncate: false, addressType: wallet.type })
                  : wallet.id}
              </span>
            </p>
            {solBalance !== null && (
              <p className="text-sm text-gray-700">
                Balance: <span className="font-mono">{solBalance} SOL</span>
              </p>
            )}
            {swigAddress && (
              <p className="text-sm text-gray-700">
                Swig address: <span className="font-mono break-all">{swigAddress}</span>
              </p>
            )}
          </div>
        )}
        <div className="flex justify-center">
          <div className="w-full max-w-xs gap-4 flex flex-col">
            {account?.isConnected && (
              <button
                onClick={createSwigAccount}
                disabled={isCreatingSwig}
                className="w-full px-4 py-2 bg-blue-600 text-white rounded-md hover:bg-blue-700 disabled:bg-blue-400"
              >
                {isCreatingSwig ? "Creating Swig..." : "Create Swig"}
              </button>
            )}
            <LoginButton />
          </div>
        </div>
      </div>
    </div>
  );
};
```

### Create the Login Button Component

Create `LoginButton.tsx` in `src/components/`:

```typescript theme={null}
import React from "react";
import { ParaModal, useModal, OAuthMethod, useAccount, useLogout } from "@getpara/react-sdk";

export const LoginButton: React.FC = () => {
  const { openModal } = useModal();
  const { data: account } = useAccount();
  const { logoutAsync } = useLogout();

  const handleClick = () => {
    if (account?.isConnected) {
      logoutAsync();
    } else {
      openModal();
    }
  };

  return (
    <>
      <button
        onClick={handleClick}
        className={`w-full px-4 py-2 rounded-md ${
          account?.isConnected
            ? "bg-gray-200 text-gray-700 hover:bg-gray-300"
            : "bg-blue-600 text-white hover:bg-blue-700"
        }`}
      >
        {account?.isConnected ? "Sign out" : "Sign in with Para"}
      </button>

      <ParaModal
        appName="Para Modal Example"
        logo="https://onswig.com/raccoon-logo.svg"
        oAuthMethods={[OAuthMethod.GOOGLE, OAuthMethod.TWITTER, OAuthMethod.DISCORD]}
      />
    </>
  );
};
```

## 4. Understanding the Implementation

### Para Modal Integration

The Para modal handles:

* User authentication via OAuth providers
* Wallet creation and management
* Secure key storage

> 💡 Para abstracts away the complexity of wallet creation and management

### Swig Account Creation

The `createSwigAccount` function:

1. Generates a unique ID for the Swig account
2. Creates a Para Solana signer
3. Sets up root authority with full permissions
4. Builds and signs the transaction using Para's signer
5. Sends the transaction to create the Swig account

> 🔒 The Para-generated wallet becomes the root authority for the Swig account

### Important Notes

1. **Devnet SOL**: Before creating the Swig account, you need to send devnet SOL to the Para-generated wallet address.

2. **Error Handling**: The implementation includes proper error handling and loading states.

3. **Balance Display**: The UI shows the wallet's SOL balance and Swig address after creation.

## Running the Application

1. Start the development server:

```bash theme={null}
yarn dev
```

2. Open your browser to the displayed URL (usually `http://localhost:5173`)

3. Click "Sign in with Para" to authenticate

4. After authentication, send some devnet SOL to your wallet address

5. Click "Create Swig" to create your Swig account

## Next Steps

Now that you have a Swig account with Para integration, you can:

* Implement additional Swig functionality (transfers, token management, etc.)
* Customize the Para modal appearance
* Add more OAuth providers
* Implement additional security features

For more information, check out:

* [Para Documentation](https://docs.getpara.com)
* [Swig SDK Documentation](/reference/typescript)
* [Example Source Code](https://github.com/anagrambuild/swig-sdk-dapp-examples/tree/main/apps/para-modal-example)


# 1. Creating a Swig
Source: https://build.onswig.com/tutorials/typescript/create

"A journey of a thousand steps starts with one Swig." - Somebody

Before we begin our quest lets make sure you have the basics ready so lets set up a basic project, if you have already done this, feel free to move on. If you have not finished step 0 in this tutorial please go back and run through that as we refer back and depend on this step.

Now that you have your environment all setup and ready to role, make a new file called `tutorial.ts`, make sure you are in the `examples/tutorial/classic` folder for the `classic` version and `examples/tutorial/kit` folder for `kit`. Don't forget to start your validator with `bun start-validator`

```bash theme={null}
mkdir tutorial && touch tutorial-1.ts 
```

Open that file up in your favorite editor, or AI overlord super virtual reality goggles. Lets make a function called `createSwigAccount`

## Example

<Tabs>
  <Tab title="Classic">
    ```typescript theme={null}
    import {
      Connection,
      Keypair,
      LAMPORTS_PER_SOL,
      Transaction,
      sendAndConfirmTransaction,
    } from "@solana/web3.js";

    import {
      Actions,
      createEd25519AuthorityInfo,
      findSwigPda,
      getCreateSwigInstruction,
    } from "@swig-wallet/classic";

    import chalk from "chalk";

    async function createSwigAccount(connection: Connection, user: Keypair) {
      try {
        const id = new Uint8Array(32);
        crypto.getRandomValues(id);
        const swigAddress = findSwigPda(id);
        const rootAuthorityInfo = createEd25519AuthorityInfo(user.publicKey);
        const rootActions = Actions.set().manageAuthority().get();

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

        const transaction = new Transaction().add(createSwigIx);
        const signature = await sendAndConfirmTransaction(connection, transaction, [
          user,
        ]);

        console.log(
          chalk.green("✓ Swig account created at:"),
          chalk.cyan(swigAddress.toBase58()),
        );
        console.log(chalk.blue("Transaction signature:"), chalk.cyan(signature));
        return swigAddress;
      } catch (error) {
        console.error(
          chalk.red("✗ Error creating Swig account:"),
          chalk.red(error),
        );
        throw error;
      }
    }

    (async () => {
      console.log(chalk.blue("🚀 Starting tutorial"));
      const connection = new Connection("http://localhost:8899", "confirmed");
      const userKeypair = Keypair.generate();
      const f = await connection.requestAirdrop(
        userKeypair.publicKey,
        100 * LAMPORTS_PER_SOL,
      );
      const blockhash = await connection.getLatestBlockhash();
      await connection.confirmTransaction({
        signature: f,
        blockhash: blockhash.blockhash,
        lastValidBlockHeight: blockhash.lastValidBlockHeight,
      });
      console.log(
        chalk.green("👤 User public key:"),
        chalk.cyan(userKeypair.publicKey.toBase58()),
      );
      const swigAddress = await createSwigAccount(connection, userKeypair);
      setTimeout(() => {
        console.log(chalk.green("\n✨ Everything looks good!"));
        console.log(
          chalk.yellow("🔍 Check out your transaction on Solana Explorer:"),
        );
        console.log(
          chalk.cyan(
            `https://explorer.solana.com/address/${swigAddress.toBase58()}?cluster=custom&customUrl=http%3A%2F%2Flocalhost%3A8899`,
          ),
        );
      }, 2000);
    })();
    ```
  </Tab>

  <Tab title="Kit">
    ```typescript theme={null}
    import {
      createSolanaRpc,
      createSolanaRpcSubscriptions,
      generateKeyPairSigner,
      sendAndConfirmTransactionFactory,
      signTransactionMessageWithSigners,
      getSignatureFromTransaction,
      lamports,
      pipe,
      createTransactionMessage,
      setTransactionMessageFeePayerSigner,
      setTransactionMessageLifetimeUsingBlockhash,
      appendTransactionMessageInstructions,
      addSignersToTransactionMessage,
      type IInstruction,
      type KeyPairSigner,
      type Blockhash,
    } from '@solana/kit';

    import {
      Actions,
      createEd25519AuthorityInfo,
      findSwigPda,
      getCreateSwigInstruction,
    } from '@swig-wallet/kit';

    import chalk from 'chalk';
    import { sleepSync } from 'bun';

    // ---------------------------------------
    // Util
    // ---------------------------------------
    function randomBytes(length: number): Uint8Array {
      const array = new Uint8Array(length);
      crypto.getRandomValues(array);
      return array;
    }

    function getTransactionMessage<Inst extends IInstruction[]>(
      instructions: Inst,
      latestBlockhash: Readonly<{
        blockhash: Blockhash;
        lastValidBlockHeight: bigint;
      }>,
      feePayer: KeyPairSigner,
      signers: KeyPairSigner[] = [],
    ) {
      return pipe(
        createTransactionMessage({ version: 0 }),
        (tx) => setTransactionMessageFeePayerSigner(feePayer, tx),
        (tx) => setTransactionMessageLifetimeUsingBlockhash(latestBlockhash, tx),
        (tx) => appendTransactionMessageInstructions(instructions, tx),
        (tx) => addSignersToTransactionMessage(signers, tx),
      );
    }

    async function sendTransaction<T extends IInstruction[]>(
      connection: {
        rpc: ReturnType<typeof createSolanaRpc>;
        rpcSubscriptions: ReturnType<typeof createSolanaRpcSubscriptions>;
      },
      instructions: T,
      payer: KeyPairSigner,
      signers: KeyPairSigner[] = [],
    ) {
      const { value: latestBlockhash } = await connection.rpc
        .getLatestBlockhash()
        .send();
      const transactionMessage = getTransactionMessage(
        instructions,
        latestBlockhash,
        payer,
        signers,
      );
      const signedTransaction =
        await signTransactionMessageWithSigners(transactionMessage);

      await sendAndConfirmTransactionFactory(connection as any)(signedTransaction, {
        commitment: 'confirmed',
      });

      const signature = getSignatureFromTransaction(signedTransaction);

      return signature.toString();
    }

    // ---------------------------------------
    // Create Swig Account
    // ---------------------------------------
    async function createSwigAccount(
      connection: {
        rpc: ReturnType<typeof createSolanaRpc>;
        rpcSubscriptions: ReturnType<typeof createSolanaRpcSubscriptions>;
      },
      user: KeyPairSigner,
    ) {
      try {
        const id = randomBytes(32);
        const swigAddress = await findSwigPda(id);
        const authorityInfo = createEd25519AuthorityInfo(user.address);
        const actions = Actions.set().manageAuthority().get();

        const ix = await getCreateSwigInstruction({
          payer: user.address,
          id,
          authorityInfo,
          actions,
        });

        const sig = await sendTransaction(connection, [ix], user);

        console.log(
          chalk.green('✓ Swig account created at:'),
          chalk.cyan(swigAddress.toString()),
        );
        console.log(chalk.blue('Transaction signature:'), chalk.cyan(sig));
        return swigAddress;
      } catch (error) {
        console.error(chalk.red('✗ Error creating Swig account:'), chalk.red(error));
        throw error;
      }
    }

    // ---------------------------------------
    // Main
    // ---------------------------------------
    (async () => {
      console.log(chalk.blue('🚀 Starting tutorial'));

      const connection = {
        rpc: createSolanaRpc('http://localhost:8899'),
        rpcSubscriptions: createSolanaRpcSubscriptions('ws://localhost:8900'),
      };

      const user = await generateKeyPairSigner();

      // Airdrop
      await connection.rpc
        .requestAirdrop(user.address, lamports(BigInt(100 * 1_000_000_000)))
        .send();

      await sleepSync(2000);

      console.log(
        chalk.green('👤 User public key:'),
        chalk.cyan(user.address.toString()),
      );

      const swigAddress = await createSwigAccount(connection, user);

      setTimeout(() => {
        console.log(chalk.green('\n✨ Everything looks good!'));
        console.log(
          chalk.yellow('🔍 Check out your transaction on Solana Explorer:'),
        );
        console.log(
          chalk.cyan(
            `https://explorer.solana.com/address/${swigAddress.toString()}?cluster=custom&customUrl=http%3A%2F%2Flocalhost%3A8899`,
          ),
        );
      }, 2000);
    })();
    ```
  </Tab>
</Tabs>

Lets save this and get ready to run it, but before we do lets break it down step by step.

## 1. Import Required SDKs

<Tabs>
  <Tab title="Classic">
    ```typescript theme={null}
    import {
      Connection,
      Keypair,
      LAMPORTS_PER_SOL,
      Transaction,
      sendAndConfirmTransaction,
    } from '@solana/web3.js';

    import {
      Actions,
      createEd25519AuthorityInfo,
      findSwigPda,
      getCreateSwigInstruction,
    } from '@swig-wallet/classic';
    ```
  </Tab>

  <Tab title="Kit">
    ```typescript theme={null}
    import {
      createSolanaRpc,
      createSolanaRpcSubscriptions,
      generateKeyPairSigner,
      sendAndConfirmTransactionFactory,
      signTransactionMessageWithSigners,
      getSignatureFromTransaction,
      lamports,
      pipe,
      createTransactionMessage,
      setTransactionMessageFeePayerSigner,
      setTransactionMessageLifetimeUsingBlockhash,
      appendTransactionMessageInstructions,
      addSignersToTransactionMessage,
      type IInstruction,
      type KeyPairSigner,
      type Blockhash,
    } from '@solana/kit';

    import {
      Actions,
      createEd25519AuthorityInfo,
      findSwigPda,
      getCreateSwigInstruction,
    } from '@swig-wallet/kit';
    ```
  </Tab>
</Tabs>

Imports Solana primitives and essential utilities from the Swig SDK.

## 2. Generate a Unique Swig ID

<Tabs>
  <Tab title="Classic">
    ```typescript theme={null}
    const id = new Uint8Array(32);
    crypto.getRandomValues(id);
    ```
  </Tab>

  <Tab title="Kit">
    ```typescript theme={null}
    function randomBytes(length: number): Uint8Array {
      const array = new Uint8Array(length);
      crypto.getRandomValues(array);
      return array;
    }

    const id = randomBytes(32);
    ```
  </Tab>
</Tabs>

Generates a secure 32-byte ID that uniquely identifies this Swig wallet instance. This ID is used to derive the PDA (Program Derived Address).

> 💡 This can really be anything, as long as it's globally unique. You can even use other public keys, strings, or a boring old number if needed.

## 3. Derive the Swig PDA

<Tabs>
  <Tab title="Classic">
    ```typescript theme={null}
    const [swigAddress] = findSwigPda(id);
    ```
  </Tab>

  <Tab title="Kit">
    ```typescript theme={null}
    const swigAddress = await findSwigPda(id);
    ```
  </Tab>
</Tabs>

Computes the wallet's on-chain PDA using the generated ID. This is the unique address of the Swig account on Solana.

> 🧠 This is a standard Solana pattern—Swig just makes it easier.

## 4. Create the Root Role

Swig is role-based: it combines Authorities (who) and Actions (what) to determine permissions. This section builds the root role.

<Tabs>
  <Tab title="Classic">
    ```typescript theme={null}
    const rootAuthority = createEd25519AuthorityInfo(user.publicKey);
    const rootActions = Actions.set().manageAuthority().get();
    ```
  </Tab>

  <Tab title="Kit">
    ```typescript theme={null}
    const authorityInfo = createEd25519AuthorityInfo(user.address);
    const actions = Actions.set().manageAuthority().get();
    ```
  </Tab>
</Tabs>

This sets up the root role. Since this is the root, it must have at least `manageAuthority()` or `all()`.

> ✅ `manageAuthority()` is restrictive but safe.
>
> 🚨 `all()` gives full control—use carefully in production.

You can find all available action types in the [Swig SDK docs](https://anagrambuild.github.io/swig-ts/enums/_swig-wallet_coder.Permission.html). New types may be added over time.

Swig supports multiple Authority types—this example uses Ed25519 authorities, but others are available for different credentials or verification methods. These handle the Authentication half of Swig's model. You can find all the types of authorities on the [SDK Docs](https://anagrambuild.github.io/swig-ts/enums/_swig-wallet_coder.AuthorityType.html).

## 5. Create the Swig Account On-Chain

<Tabs>
  <Tab title="Classic">
    ```typescript theme={null}
    const createSwigIx = await getCreateSwigInstruction({
      payer: user.publicKey,
      id,
      actions: rootActions,
      authorityInfo: rootAuthority,
    });

    const transaction = new Transaction().add(createSwigIx);
    const signature = await sendAndConfirmTransaction(connection, transaction, [user]);
    ```
  </Tab>

  <Tab title="Kit">
    ```typescript theme={null}
    const ix = await getCreateSwigInstruction({
      payer: user.address,
      id,
      authorityInfo,
      actions,
    });

    const sig = await sendTransaction(connection, [ix], user);
    ```
  </Tab>
</Tabs>

Creates the Swig account by building and sending a transaction to the Solana blockchain. The transaction must be signed by the user. In this case the payer of the transaction and the rent is the user, but you can also have a different fee payer for the transaction.

## 6. Simulate a Funded User

<Tabs>
  <Tab title="Classic">
    ```typescript theme={null}
    const userKeypair = Keypair.generate();
    const f = await connection.requestAirdrop(userKeypair.publicKey, 100 * LAMPORTS_PER_SOL);
    const blockhash = await connection.getLatestBlockhash();
    await connection.confirmTransaction({
      signature: f,
      blockhash: blockhash.blockhash,
      lastValidBlockHeight: blockhash.lastValidBlockHeight,
    });
    ```
  </Tab>

  <Tab title="Kit">
    ```typescript theme={null}
    const user = await generateKeyPairSigner();

    await connection.rpc
      .requestAirdrop(user.address, lamports(BigInt(100 * 1_000_000_000)))
      .send();

    await sleepSync(2000);
    ```
  </Tab>
</Tabs>

Creates a fresh Keypair and airdrops some SOL from the local validator so it can pay for the transaction.

## 7. Connect to the Validator

<Tabs>
  <Tab title="Classic">
    ```typescript theme={null}
    const connection = new Connection('http://localhost:8899', 'confirmed');
    ```
  </Tab>

  <Tab title="Kit">
    ```typescript theme={null}
    const connection = {
      rpc: createSolanaRpc('http://localhost:8899'),
      rpcSubscriptions: createSolanaRpcSubscriptions('ws://localhost:8900'),
    };
    ```
  </Tab>
</Tabs>

Creates a connection to the local Solana cluster. Ensure you've run:

<Tabs>
  <Tab title="Classic">
    ```bash theme={null}
    bun start-validator
    ```
  </Tab>

  <Tab title="Kit">
    ```bash theme={null}
    bun start-validator
    ```
  </Tab>
</Tabs>

This spins up a local testnet with the Swig programs deployed.

## 8. Log Success

<Tabs>
  <Tab title="Classic">
    ```typescript theme={null}
    console.log(chalk.green("✓ Swig account created at:"), chalk.cyan(swigAddress.toBase58()));
    ```
  </Tab>

  <Tab title="Kit">
    ```typescript theme={null}
    console.log(chalk.green("✓ Swig account created at:"), chalk.cyan(swigAddress.toString()));
    ```
  </Tab>
</Tabs>

Prints the address of the new Swig account in a colorized format.

## Ready to run it?

```bash theme={null}
bun run ./tutorial/tutorial-1.ts
```

Congratulations on your first Swig!


# 0. Environment Setup
Source: https://build.onswig.com/tutorials/typescript/env

"One man spends and hour cutting wood, another sharpens his axe for 50 minutes and chops wood for 10 minutes" - Somebody

Before you begin writing Swig-powered apps—like wallets, token transfers, or Telegram integrations—you need to set up your development environment to support real blockchain interactions using the Swig SDK.

This setup follows the official Swig TypeScript SDK and prepares you to build and run your own scripts inside the example workspace. You'll be writing new files in the same folder as the examples so you can easily compare your code to working references.

## Prerequisites

Before starting, make sure you have the following installed:

### Option A: Node.js + Yarn

* Node.js v16 or newer
* Yarn v3+

### Option B (Preferred): Bun

Bun provides better performance and a simpler setup. Install it with:

```bash theme={null}
curl -fsSL https://bun.sh/install | bash
```

### Required Tools

Additionally, you'll need:

* Solana CLI
* Rust + Cargo

## Step 1: Clone and Install

First, clone the examples repository and install dependencies:

```bash theme={null}
# Clone the repository
git clone https://github.com/anagrambuild/swig-ts.git

# Enter the project directory
cd swig-ts

# Install dependencies
bun install
```

## Step 2: Navigate to Examples

Move into the examples directory where you'll write your code:

<Tabs>
  <Tab title="Classic">
    ```bash theme={null}
    cd examples/tutorial/classic 
    ```
  </Tab>

  <Tab title="Kit">
    ```bash theme={null}
    cd examples/tutorial/kit 
    ```
  </Tab>
</Tabs>

This location is important because it:

* Provides access to working examples (`transfer-local.ts`, `mint.ts`, etc.)
* Uses shared tooling without extra configuration
* Allows side-by-side comparison with official samples

## Step 3: Start the Validator

Start a local Solana testnet for development:

```bash theme={null}
bun start-validator
```

This command:

* Spins up a local Solana testnet
* Installs Swig programs into the testnet
* Creates a safe, reproducible environment for testing

> 💡 Keep the validator running in a separate terminal window. You only need to start it once per development session.

## Verifying Your Setup

To verify everything is working:

1. Check the validator:

```bash theme={null}
solana config get
```

You should see the local network configuration.

## Common Issues

### Validator Won't Start

If the validator fails to start:

1. Check if another validator is running:

```bash theme={null}
ps aux | grep solana-test-validator
```

2. Kill any existing processes:

```bash theme={null}
pkill solana-test-validator
```

### Installation Problems

If you encounter installation issues:

1. Clear your package cache:

```bash theme={null}
bun cache clean
```

2. Remove and reinstall dependencies:

```bash theme={null}
rm -rf node_modules
bun install
```

### Port Conflicts

If you see port conflicts:

1. Check which process is using the port:

```bash theme={null}
lsof -i :8899
```

2. Either kill the process or configure a different port in your settings.

## Development Tools

We recommend the following tools for the best development experience:

### Code Editor

* VS Code with extensions:
  * TypeScript and JavaScript Language Features
  * Solidity
  * Rust

### Browser Extensions

* Swig Wallet Extension (Coming Soon)
* Phantom Wallet
* Solflare Wallet

### Command Line Tools

* `solana-cli` for blockchain interaction
* `cargo` for Rust development
* `bun` for running TypeScript files


# Getting Started with Swig TS SDK
Source: https://build.onswig.com/tutorials/typescript/index

"The beginning of wisdom is this, get wisdom and above all get knowledge" - Solomon

Welcome to the TypeScript SWIG SDK tutorial! This comprehensive guide will walk you through all the essential functions and features of the SWIG SDK, helping you understand how to integrate SWIG into your TypeScript applications.

<Tip>
  The tutorial code is available in the
  [swig-ts](https://github.com/anagrambuild/swig-ts) repository.
  <br />- For the <b>Classic</b> version (compatible with <code>
  @solana/web3.js
  </code>), see: <code>examples/tutorial/classic</code>
  <br />- For the <b>Kit</b> version (compatible with <code>@solana/kit</code>),
  see: <code>examples/tutorial/kit</code>
</Tip>

> **Note:**\
> This tutorial provides two versions of each code example:
>
> * **Classic:** Uses the `@solana/web3.js` library and is compatible with the classic Solana SDK.
> * **Kit:** Uses the new `@solana/kit` library for a modern, streamlined Solana development experience.
>
> You can switch between Classic and Kit code snippets using the tabs above each example.

## What You'll Learn

In this tutorial, you'll learn how to:

* Set up your development environment for SWIG
* Create and manage SWIGs
* Manage authorities and permissions with
* Sign transactions using the new instruction-based approach
* Migrate from previous versions

## Time Commitment

This tutorial is designed to be completed in approximately 30 minutes. Each section builds upon the previous one, providing a clear progression through the SDK's capabilities.

## Tutorial Scope

This guide focuses on creating and managing SWIGs using regular Solana keypair authorities. While this covers the most common use cases, SWIG supports other authority types as well.

## Tutorial Sections

Follow these tutorials in order for the best learning experience:

1. [Environment Setup](./env) - Set up your development environment
2. [Creating Your First SWIG](./create) - Learn how to create and initialize a SWIG
3. [Managing Authorities and Actions](./managing_authorities) - Learn how to manage authorities and actions
4. [Signing Transactions](./sign) - Learn how to sign transactions with Swig

Let's get started with building your first SWIG!


# 2. Managing Authorities and Actions
Source: https://build.onswig.com/tutorials/typescript/managing_authorities

"The road to heaven is paved with good role based access control." - Codex Walleticus

In this tutorial, we'll learn how to add multiple authorities to a Swig account with different permission sets. We'll create a root authority that can manage other authorities, then add two specialized authorities: one for SOL spending and another for token management.

## Prerequisites

Before starting this tutorial:

1. Make sure you're in the `examples/tutorial/classic` directory for the `classic` version and `examples/tutorial/kit` for `kit`
2. Ensure your local validator is running with:
   ```bash theme={null}
   bun start-validator
   ```

## Quick Review

In [Tutorial 1](./tutorial-1.md), we learned how to create a basic Swig account. Now we'll expand on that by managing multiple authorities with different permissions.

```bash theme={null}
mkdir tutorial && touch tutorial-2.ts
```

Open that file up in your favorite editor, or AI overlord super virtual reality goggles. Lets make a function called `addNewAuthority`

## Example

<Tabs>
  <Tab title="Classic">
    ```typescript theme={null}
    import {
      Connection,
      Keypair,
      LAMPORTS_PER_SOL,
      PublicKey,
      Transaction,
      sendAndConfirmTransaction,
    } from "@solana/web3.js";

    import {
      Actions,
      createEd25519AuthorityInfo,
      fetchSwig,
      findSwigPda,
      getAddAuthorityInstructions,
      getCreateSwigInstruction,
    } from "@swig-wallet/classic";

    import chalk from "chalk";

    async function createSwigAccount(connection: Connection, user: Keypair) {
      try {
        const id = new Uint8Array(32);
        crypto.getRandomValues(id);
        const swigAddress = findSwigPda(id);
        const rootAuthorityInfo = createEd25519AuthorityInfo(user.publicKey);
        const rootActions = Actions.set().manageAuthority().get();

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

        const transaction = new Transaction().add(createSwigIx);
        const signature = await sendAndConfirmTransaction(connection, transaction, [
          user,
        ]);

        console.log(
          chalk.green("✓ Swig account created at:"),
          chalk.cyan(swigAddress.toBase58()),
        );
        console.log(chalk.blue("Transaction signature:"), chalk.cyan(signature));
        return swigAddress;
      } catch (error) {
        console.error(
          chalk.red("✗ Error creating Swig account:"),
          chalk.red(error),
        );
        throw error;
      }
    }

    async function addNewAuthority(
      connection: Connection,
      rootUser: Keypair,
      newAuthority: Keypair,
      swigAddress: PublicKey,
      actions: any,
      description: string,
    ) {
      try {
        const swig = await fetchSwig(connection, swigAddress);

        const rootRole = swig.findRolesByEd25519SignerPk(rootUser.publicKey)[0];
        if (!rootRole) {
          throw new Error("Root role not found for authority");
        }

        const addAuthorityInstructions = await getAddAuthorityInstructions(
          swig,
          rootRole.id,
          createEd25519AuthorityInfo(newAuthority.publicKey),
          actions,
        );

        const transaction = new Transaction().add(...addAuthorityInstructions);
        await sendAndConfirmTransaction(connection, transaction, [rootUser]);
        console.log(
          chalk.green(`✓ New ${description} authority added:`),
          chalk.cyan(newAuthority.publicKey.toBase58()),
        );
      } catch (error) {
        console.error(
          chalk.red(`✗ Error adding ${description} authority:`),
          chalk.red(error),
        );
        throw error;
      }
    }

    (async () => {
      console.log(chalk.blue('🚀 Starting tutorial - Adding Multiple Authorities'));

      // Connect to local Solana network
      const connection = new Connection("http://localhost:8899", "confirmed");

      const rootUser = Keypair.generate();
      console.log(
        chalk.green("👤 Root user public key:"),
        chalk.cyan(rootUser.publicKey.toBase58()),
      );

      const airdrop = await connection.requestAirdrop(
        rootUser.publicKey,
        100 * LAMPORTS_PER_SOL,
      );
      const blockhash = await connection.getLatestBlockhash();
      await connection.confirmTransaction({
        signature: airdrop,
        blockhash: blockhash.blockhash,
        lastValidBlockHeight: blockhash.lastValidBlockHeight,
      });

      console.log(chalk.yellow('\n📝 Creating Swig account...'));
      const swigAddress = await createSwigAccount(connection, rootUser);

      const spendingAuthority = Keypair.generate();
      console.log(
        chalk.green("\n👥 Spending authority public key:"),
        chalk.cyan(spendingAuthority.publicKey.toBase58()),
      );

      // Create the token authority
      const tokenAuthority = Keypair.generate();
      console.log(
        chalk.green("👥 Token authority public key:"),
        chalk.cyan(tokenAuthority.publicKey.toBase58()),
      );

      // Add some delay to ensure the Swig account is created
      await new Promise((resolve) => setTimeout(resolve, 2000));

      const spendingActions = Actions.set()
        .solLimit({ amount: BigInt(0.1 * LAMPORTS_PER_SOL) })
        .get();

      await addNewAuthority(
        connection,
        rootUser,
        spendingAuthority,
        swigAddress,
        spendingActions,
        'spending',
      );

      const tokenMint = Keypair.generate().publicKey;
      const tokenActions = Actions.set()
        .tokenLimit({ mint: tokenMint, amount: BigInt(1000000) })
        .get();

      await addNewAuthority(
        connection,
        rootUser,
        tokenAuthority,
        swigAddress,
        tokenActions,
        'token',
      );

      const swig = await fetchSwig(connection, swigAddress);

      console.log(chalk.blue('\n📊 Authority Permissions:'));

      const spendingRole = swig.findRolesByEd25519SignerPk(
        spendingAuthority.publicKey,
      )[0];
      console.log(chalk.yellow('Spending Authority:'));
      console.log(
        '- Can spend SOL:',
        chalk.green(
          spendingRole.actions.canSpendSol(BigInt(0.1 * LAMPORTS_PER_SOL)),
        ),
      );
      console.log(
        '- Can spend tokens:',
        chalk.red(spendingRole.actions.canSpendToken(tokenMint, BigInt(1000000))),
      );

      const tokenRole = swig.findRolesByEd25519SignerPk(
        tokenAuthority.publicKey,
      )[0];
      console.log(chalk.yellow('\nToken Authority:'));
      console.log(
        '- Can spend SOL:',
        chalk.red(tokenRole.actions.canSpendSol(BigInt(0.1 * LAMPORTS_PER_SOL))),
      );
      console.log(
        '- Can spend tokens:',
        chalk.green(tokenRole.actions.canSpendToken(tokenMint, BigInt(1000000))),
      );

      console.log(chalk.green('\n✨ Tutorial completed successfully!'));
      console.log(
        chalk.yellow('🔍 Check out your transaction on Solana Explorer:'),
      );
      console.log(
        chalk.cyan(
          `https://explorer.solana.com/address/${swigAddress}?cluster=custom&customUrl=http%3A%2F%2Flocalhost%3A8899`,
        ),
      );
    })();
    ```
  </Tab>

  <Tab title="Kit">
    ```typescript theme={null}
    import {
      createSolanaRpc,
      createSolanaRpcSubscriptions,
      generateKeyPairSigner,
      getSignatureFromTransaction,
      lamports,
      pipe,
      sendAndConfirmTransactionFactory,
      signTransactionMessageWithSigners,
      createTransactionMessage,
      setTransactionMessageFeePayerSigner,
      setTransactionMessageLifetimeUsingBlockhash,
      appendTransactionMessageInstructions,
      addSignersToTransactionMessage,
      type Address,
      type Blockhash,
      type IInstruction,
      type KeyPairSigner,
    } from '@solana/kit';

    import {
      Actions,
      createEd25519AuthorityInfo,
      fetchSwig,
      findSwigPda,
      getAddAuthorityInstructions,
      getCreateSwigInstruction,
    } from '@swig-wallet/kit';

    import chalk from 'chalk';
    import { sleepSync } from 'bun';

    function randomBytes(length: number): Uint8Array {
      const arr = new Uint8Array(length);
      crypto.getRandomValues(arr);
      return arr;
    }

    function getTransactionMessage<Inst extends IInstruction[]>(
      instructions: Inst,
      latestBlockhash: Readonly<{
        blockhash: Blockhash;
        lastValidBlockHeight: bigint;
      }>,
      feePayer: KeyPairSigner,
      signers: KeyPairSigner[] = [],
    ) {
      return pipe(
        createTransactionMessage({ version: 0 }),
        (tx) => setTransactionMessageFeePayerSigner(feePayer, tx),
        (tx) => setTransactionMessageLifetimeUsingBlockhash(latestBlockhash, tx),
        (tx) => appendTransactionMessageInstructions(instructions, tx),
        (tx) => addSignersToTransactionMessage(signers, tx),
      );
    }

    async function sendTransaction<T extends IInstruction[]>(
      connection: {
        rpc: ReturnType<typeof createSolanaRpc>;
        rpcSubscriptions: ReturnType<typeof createSolanaRpcSubscriptions>;
      },
      instructions: T,
      payer: KeyPairSigner,
      signers: KeyPairSigner[] = [],
    ) {
      const { value: latestBlockhash } = await connection.rpc
        .getLatestBlockhash()
        .send();
      const txMsg = getTransactionMessage(instructions, latestBlockhash, payer, signers);
      const signedTx = await signTransactionMessageWithSigners(txMsg);
      await sendAndConfirmTransactionFactory(connection as any)(signedTx, { commitment: 'confirmed' });
      return getSignatureFromTransaction(signedTx).toString();
    }

    async function createSwigAccount(connection: any, user: KeyPairSigner) {
      const id = randomBytes(32);
      const swigAddress = await findSwigPda(id);
      const rootActions = Actions.set().manageAuthority().get();
      const authorityInfo = createEd25519AuthorityInfo(user.address);

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

      const sig = await sendTransaction(connection, [ix], user);

      console.log(chalk.green('✓ Swig account created at:'), chalk.cyan(swigAddress.toString()));
      console.log(chalk.blue('Transaction signature:'), chalk.cyan(sig));

      return { swigAddress, transactionSignature: sig };
    }

    async function addNewAuthority(
      connection: any,
      rootUser: KeyPairSigner,
      newAuthority: KeyPairSigner,
      swigAddress: Address,
      actions: any, // Actions built from the Actions builder pattern
      description: string,
    ) {
      const swig = await fetchSwig(connection.rpc, swigAddress);
      const rootRole = swig.findRolesByEd25519SignerPk(rootUser.address)[0];
      if (!rootRole) throw new Error('Root role not found');

      const ix = await getAddAuthorityInstructions(
        swig,
        rootRole.id,
        createEd25519AuthorityInfo(newAuthority.address),
        actions,
      );

      await sendTransaction(connection, ix, rootUser);

      console.log(
        chalk.green(`✓ New ${description} authority added:`),
        chalk.cyan(newAuthority.address.toString()),
      );
    }

    (async () => {
      console.log(chalk.blue('🚀 Starting tutorial - Swig + Kit style'));

      const connection = {
        rpc: createSolanaRpc('http://localhost:8899'),
        rpcSubscriptions: createSolanaRpcSubscriptions('ws://localhost:8900'),
      };

      const rootUser = await generateKeyPairSigner();
      console.log(chalk.green('👤 Root user public key:'), chalk.cyan(rootUser.address.toString()));

      await connection.rpc
        .requestAirdrop(rootUser.address, lamports(BigInt(100 * 1_000_000_000)))
        .send();

      sleepSync(2000);

      console.log(chalk.yellow('\n📝 Creating Swig account...'));
      const { swigAddress } = await createSwigAccount(connection, rootUser);

      const spendingAuthority = await generateKeyPairSigner();
      const tokenAuthority = await generateKeyPairSigner();

      console.log(chalk.green('\n👥 Spending authority public key:'), chalk.cyan(spendingAuthority.address.toString()));
      console.log(chalk.green('👥 Token authority public key:'), chalk.cyan(tokenAuthority.address.toString()));

      sleepSync(2000);

      const spendingActions = Actions.set()
        .solLimit({ amount: BigInt(0.1 * 1_000_000_000) })
        .get();

      await addNewAuthority(connection, rootUser, spendingAuthority, swigAddress, spendingActions, 'spending');

      const fakeMint = await generateKeyPairSigner();
      const tokenActions = Actions.set()
        .tokenLimit({ mint: fakeMint.address, amount: BigInt(1_000_000) })
        .get();

      await addNewAuthority(connection, rootUser, tokenAuthority, swigAddress, tokenActions, 'token');

      const swig = await fetchSwig(connection.rpc, swigAddress);

      console.log(chalk.blue('\n📊 Authority Permissions:'));

      const spendingRole = swig.findRolesByEd25519SignerPk(spendingAuthority.address)[0];
      console.log(chalk.yellow('Spending Authority:'));
      console.log(
        '- Can spend SOL:',
        chalk.green(spendingRole.actions.canSpendSol(BigInt(0.1 * 1_000_000_000))),
      );
      console.log(
        '- Can spend tokens:',
        chalk.red(spendingRole.actions.canSpendToken(fakeMint.address, BigInt(1_000_000))),
      );

      const tokenRole = swig.findRolesByEd25519SignerPk(tokenAuthority.address)[0];
      console.log(chalk.yellow('\nToken Authority:'));
      console.log(
        '- Can spend SOL:',
        chalk.red(tokenRole.actions.canSpendSol(BigInt(0.1 * 1_000_000_000))),
      );
      console.log(
        '- Can spend tokens:',
        chalk.green(tokenRole.actions.canSpendToken(fakeMint.address, BigInt(1_000_000))),
      );

      console.log(chalk.green('\n✨ Tutorial completed successfully!'));
      console.log(chalk.yellow('🔍 Check out your transaction on Solana Explorer:'));
     console.log(
        chalk.cyan(
          `https://explorer.solana.com/address/${swigAddress}?cluster=custom&customUrl=http%3A%2F%2Flocalhost%3A8899`,
        ),
      );
    })();
    ```
  </Tab>
</Tabs>

## Code Breakdown

Let's examine the key parts of `tutorial-2.ts`:

### 1. Creating a Root Authority

<Tabs>
  <Tab title="Classic">
    ```typescript theme={null}
    const rootActions = Actions.set().manageAuthority().get();
    const createSwigIx = await getCreateSwigInstruction({
      payer: user.publicKey,
      id,
      actions: rootActions,
      authorityInfo: createEd25519AuthorityInfo(user.publicKey),
    });

    const transaction = new Transaction().add(createSwigIx);
    const signature = await sendAndConfirmTransaction(connection, transaction, [user]);
    ```
  </Tab>

  <Tab title="Kit">
    ```typescript theme={null}
    const rootActions = Actions.set().manageAuthority().get();
    const authorityInfo = createEd25519AuthorityInfo(user.address);

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

    const sig = await sendTransaction(connection, [ix], user);
    ```
  </Tab>
</Tabs>

This creates a Swig account where the root authority has permission to manage other authorities. We specifically use `.manageAuthority()` to limit this authority to only managing other authorities.

### 2. Adding a SOL Spending Authority

Don't forget that the full list of actions an authority can have is [here](https://anagrambuild.github.io/swig-ts/enums/_swig-wallet_coder.Permission.html).

<Tabs>
  <Tab title="Classic">
    ```typescript theme={null}
    const spendingActions = Actions.set()
      .solLimit({ amount: BigInt(0.1 * LAMPORTS_PER_SOL) })
      .get();

    await addNewAuthority(
      connection,
      rootUser,
      spendingAuthority,
      swigAddress,
      spendingActions,
      "spending"
    );
    ```
  </Tab>

  <Tab title="Kit">
    ```typescript theme={null}
    const spendingActions = Actions.set()
      .solLimit({ amount: BigInt(0.1 * 1_000_000_000) })
      .get();

    await addNewAuthority(
      connection,
      rootUser,
      spendingAuthority,
      swigAddress,
      spendingActions,
      "spending"
    );
    ```
  </Tab>
</Tabs>

This creates an authority that:

* Can only spend SOL (no token permissions)
* Has a spending limit of 0.1 SOL
* Cannot manage other authorities

### 3. Adding a Token Authority

<Tabs>
  <Tab title="Classic">
    ```typescript theme={null}
    const tokenMint = Keypair.generate().publicKey; // Example token mint
    const tokenActions = Actions.set()
      .tokenLimit({ mint: tokenMint, amount: BigInt(1000000) })
      .get();

    await addNewAuthority(
      connection,
      rootUser,
      tokenAuthority,
      swigAddress,
      tokenActions,
      "token"
    );
    ```
  </Tab>

  <Tab title="Kit">
    ```typescript theme={null}
    const fakeMint = await generateKeyPairSigner();
    const tokenActions = Actions.set()
      .tokenLimit({ mint: fakeMint.address, amount: BigInt(1_000_000) })
      .get();

    await addNewAuthority(
      connection,
      rootUser,
      tokenAuthority,
      swigAddress,
      tokenActions,
      "token"
    );
    ```
  </Tab>
</Tabs>

This creates an authority that:

* Can only manage tokens for a specific mint
* Has a token spending limit of 1,000,000 units
* Cannot spend SOL or manage other authorities

## Understanding the Output

When you run the tutorial, you'll see:

1. The root user's public key
2. The Swig account address
3. Two new authority public keys
4. A permission summary showing what each authority can and cannot do

The tutorial provides links to view your transactions on Solana Explorer (using your local validator).

## Key Concepts

* **Root Authority**: An authority with management permissions that can add or remove other authorities
* **Specialized Authorities**: Authorities with specific, limited permissions (e.g., SOL spending or token management)
* **Permission Limits**:
  * SOL limits are set in lamports (1 SOL = 1,000,000,000 lamports)
  * Token limits are set based on the token's decimals
* **Action Sets**: Define what an authority can do using methods like:
  * `.manageAuthority()`
  * `.solLimit()`
  * `.tokenLimit()`

## Running the Tutorial

Execute the tutorial with:

```bash theme={null}
bun run ./tutorial/tutorial-2.ts
```

You nailed it , first try!! You now have a multi authority Swig, free energy and perpetual motion next.


# Migration Guide: Beta to v1.0
Source: https://build.onswig.com/tutorials/typescript/migration-v1

Complete guide for migrating from Swig TypeScript SDK beta versions to v1.0

This guide helps you migrate from the beta versions of the Swig TypeScript SDK to the completely refactored v1.0 release.

## Overview of Changes

The v1.0 release represents an overhaul with some breaking changes.

### Key Changes

1. **Modular Architecture**: Core logic moved to `@swig-wallet/lib`
2. **Instruction-Based API**: Functions return `TransactionInstruction[]` instead of single instructions
3. **Simplified Package Structure**: `@swig-wallet/classic` now acts as a thin wrapper
4. **Updated Dependencies**: Moved from `@solana/spl-token` to `@solana-program/token`

## Package Changes

### Before (Beta)

```typescript theme={null}
import {
  Actions,
  createSwig,
  Ed25519Authority,
  addAuthorityInstruction,
  signInstruction,
} from "@swig-wallet/classic";
```

### After (v1.0)

#### For Web3.js 1.x applications:

```typescript theme={null}
import {
  Actions,
  getCreateSwigInstruction,
  createEd25519AuthorityInfo,
  getAddAuthorityInstructions,
  getSignInstructions,
} from "@swig-wallet/classic";
```

#### For Web3.js 2.0 applications:

```typescript theme={null}
import {
  Actions,
  getCreateSwigInstruction,
  createEd25519AuthorityInfo,
  getAddAuthorityInstructions,
  getSignInstructions,
} from "@swig-wallet/kit";
```

### After (v1.0)

```typescript theme={null}
import {
  Actions,
  getCreateSwigInstruction,
  createEd25519AuthorityInfo,
  getAddAuthorityInstructions,
  getSignInstructions,
} from "@swig-wallet/classic";
```

## Function Migrations

### Creating a Swig

#### Before (Beta)

```typescript theme={null}
const rootAuthority = Ed25519Authority.fromPublicKey(user.publicKey);
const rootActions = Actions.set().manageAuthority().get();
const tx = await createSwig(
  connection,
  id,
  rootAuthority,
  rootActions,
  user.publicKey,
  [user],
);
```

#### After (v1.0)

```typescript theme={null}
const rootAuthorityInfo = createEd25519AuthorityInfo(user.publicKey);
```

## Swig Class Changes

The Swig class has been significantly refactored. All static methods have been removed and replaced with standalone functions.

### Static Method Removal

#### Before (Beta)

```typescript theme={null}
// Creating a Swig
const createSwigIx = Swig.create({
  payer: user.publicKey,
  id,
  actions: rootActions,
  authorityInfo: rootAuthorityInfo,
});

// Fetching a Swig
const swig = await Swig.fetch(connection, swigAddress);

// Fetching with null handling
const swig = await Swig.fetchNullable(connection, swigAddress);
```

#### After (v1.0)

```typescript theme={null}
// Creating a Swig
const createSwigIx = await getCreateSwigInstruction({
  payer: user.publicKey,
  id,
  actions: rootActions,
  authorityInfo: rootAuthorityInfo,
});

// Fetching a Swig
const swig = await fetchSwig(connection, swigAddress);

// Fetching with null handling
const swig = await fetchNullableSwig(connection, swigAddress);
```

### Instance Method Changes

The Swig instance methods remain largely the same, but some may have changed from synchronous to asynchronous:

```typescript theme={null}
// These methods are still available on Swig instances
const role = swig.findRoleById(roleId);
const roles = swig.findRolesByEd25519SignerPk(publicKey);
const roles = swig.findRolesBySecp256k1SignerAddress(address);
```

## New Sub-Account Functions

The v1.0 release introduces several new sub-account management functions:

```typescript theme={null}
// Create sub-account
const createSubAccountInstructions = await getCreateSubAccountInstructions(
  swig,
  roleId,
  options
);

// Toggle sub-account enabled/disabled
const toggleSubAccountInstructions = await getToggleSubAccountInstructions(
  swig,
  roleId,
  enabled, // boolean
  options
);

// Withdraw from sub-account
const withdrawInstructions = await getWithdrawFromSubAccountSubAccountInstructions(
  swig,
  roleId,
  withdrawArgs,
  options
);
```

## Authority Creation Changes

### Before (Beta)

```typescript theme={null}
const rootAuthority = Ed25519Authority.fromPublicKey(user.publicKey);
```

### After (v1.0)

```typescript theme={null}
const rootAuthorityInfo = createEd25519AuthorityInfo(user.publicKey);
```

## Import Changes

The v1.0 release represents a complete restructuring of the package exports. Most functionality has been moved to `@swig-wallet/lib` and re-exported through the classic package.

### Package Structure Changes

#### Before (Beta) - Direct Module Exports

```typescript theme={null}
// Beta exported many modules directly
export * from '@swig-wallet/coder';
export * from './actions';
export * from './authority';      // ❌ REMOVED
export * from './consts';
export * from './instructions';
export * from './role';          // ❌ REMOVED
export * from './rpc';           // ❌ REMOVED
export * from './swig';          // ❌ REMOVED
export * from './utils';         // ❌ REMOVED
export * from './wallet';        // ❌ REMOVED
```

#### After (v1.0) - Lib-Based Exports

```typescript theme={null}
// v1.0 exports primarily from lib with thin wrapper
export * from '@swig-wallet/lib';  // ✅ Most functionality here
export * from './accounts';
export * from './consts';
export * from './instructions';    // ✅ New wrapper functions
```

### Removed Direct Imports

These modules are no longer directly exported from `@swig-wallet/classic`:

* **Authority classes**: `Ed25519Authority`, `Secp256k1Authority`, etc.
* **Role utilities**: Direct role manipulation functions
* **RPC helpers**: Connection and RPC utilities
* **Swig class**: Static methods removed, instance available via lib
* **Utils**: Utility functions moved to lib
* **Wallet**: Wallet-related functionality moved to lib

### Core Classes

* `Actions` class is now imported from `@swig-wallet/lib` (re-exported by `@swig-wallet/classic`)
* `Swig` class is now imported from `@swig-wallet/lib` (re-exported by `@swig-wallet/classic`)
* Authority classes have been completely replaced with info creation functions

### Function Naming

* `createSwig()` → `getCreateSwigInstruction()`
* `addAuthorityInstruction()` → `getAddAuthorityInstructions()`
* `signInstruction()` → `getSignInstructions()`
* `removeAuthorityInstruction()` → `getRemoveAuthorityInstructions()`
* `createSessionInstruction()` → `getCreateSessionInstructions()`
* `createSubAccountInstruction()` → `getCreateSubAccountInstructions()`
* `toggleSubAccountInstruction()` → `getToggleSubAccountInstructions()`
* `withdrawFromSubAccountInstruction()` → `getWithdrawFromSubAccountSubAccountInstructions()`

## Dependency Updates

### For Web3.js 1.x applications:

```json theme={null}
{
  "dependencies": {
    "@swig-wallet/classic": "^1.0.0",
    "@solana-program/token": "^0.5.1",
    "@solana/web3.js": "^1.98.0"
  }
}
```

### For Web3.js 2.0 applications:

```json theme={null}
{
  "dependencies": {
    "@swig-wallet/kit": "^1.0.0",
    "@solana-program/token": "^0.5.1",
    "@solana/kit": "^2.1.0"
  }
}
```

Remove old dependencies:

```bash theme={null}
npm uninstall @solana/spl-token
```

Remove old dependencies:

```bash theme={null}
npm uninstall @solana/spl-token
```

## Migration Checklist

* [ ] Update package dependencies
* [ ] Replace single instruction functions with instruction array functions
* [ ] Update authority creation from classes to info functions
* [ ] Update PDA derivation calls
* [ ] Replace `Ed25519Authority.fromPublicKey()` with `createEd25519AuthorityInfo()`
* [ ] Replace `createSessionInstruction()` with `getCreateSessionInstructions()`
* [ ] Replace sub-account functions: `createSubAccountInstruction()`, `toggleSubAccountInstruction()`, `withdrawFromSubAccountInstruction()`
* [ ] Replace Swig static methods: `Swig.create()`, `Swig.fetch()`, `Swig.fetchNullable()`
* [ ] Update function parameters from `(role, payer, ...)` to `(swig, roleId, ...)`
* [ ] Update transaction building to spread instruction arrays
* [ ] Remove direct imports of removed modules (authority, role, rpc, utils, wallet)
* [ ] Test all functionality with the new API
* [ ] Update error handling for new function signatures

## Common Migration Issues

### Issue: Functions returning arrays instead of single instructions

**Solution**: Use the spread operator when adding to transactions:

```typescript theme={null}
// Before
transaction.add(instruction);

// After
transaction.add(...instructions);
```

### Issue: Function parameter signatures changed

**Solution**: Update function calls to use new parameter structure:

```typescript theme={null}
// Before - functions took Role objects and payer PublicKey
const ix = await addAuthorityInstruction(
  rootRole,
  rootKeypair.publicKey,
  authorityInfo,
  actions
);

// After - functions take Swig instance and role ID
const instructions = await getAddAuthorityInstructions(
  swig,
  rootRole.id,
  authorityInfo,
  actions
);
```

### Issue: Import errors for removed classes

**Solution**: Replace with new function-based API:

```typescript theme={null}
// Before
import { Ed25519Authority } from "@swig-wallet/classic";
const auth = Ed25519Authority.fromPublicKey(pk);

// After
import { createEd25519AuthorityInfo } from "@swig-wallet/classic";
const authInfo = createEd25519AuthorityInfo(pk);
```

### Issue: Swig static methods no longer available

**Solution**: Use the new standalone functions:

```typescript theme={null}
// Before
const createIx = Swig.create(args);
const swig = await Swig.fetch(connection, address);
const swig = await Swig.fetchNullable(connection, address);

// After
const createIx = await getCreateSwigInstruction(args);
const swig = await fetchSwig(connection, address);
// For nullable fetch
const swig = await fetchNullableSwig(connection, swigAddress);
```

### Issue: Sub-account functions not found

**Solution**: Use the new instruction array functions:

```typescript theme={null}
// Before
const ix = await createSubAccountInstruction(role, payer, options);

// After
const instructions = await getCreateSubAccountInstructions(swig, roleId, options);
const transaction = new Transaction().add(...instructions);
```

## Getting Help

If you encounter issues during migration:

1. Check the [API documentation](https://anagrambuild.github.io/swig-ts/modules.html)
2. Review the updated [tutorials](./index)
3. Examine the [example code](https://github.com/anagrambuild/swig-ts/tree/main/examples/tutorial/classic)
4. Open an issue on the [GitHub repository](https://github.com/anagrambuild/swig-ts/issues)

The v1.0 release is designed to be more consistent and composable, making it easier to build complex Swig applications once you've completed the migration.


# 3. Signing with Swig
Source: https://build.onswig.com/tutorials/typescript/sign

"I came. I saw. I signed it with Swig." - Julius Caesar, probably

Now that we have our Swig account set up with proper authorities from the previous tutorials, let's explore how to sign transactions. If you haven't completed the previous tutorials, please go back and complete them first as we'll be building on those concepts.

Create a new file called `tutorial-3.ts` in your `examples/tutorial/classic` directory for the `classic` version or `examples/tutorial/kit` for `kit`:

```bash theme={null}
touch tutorial/tutorial-3.ts
```

## Example

<Tabs>
  <Tab title="Classic">
    ```typescript theme={null}
    import {
      Connection,
      Keypair,
      LAMPORTS_PER_SOL,
      PublicKey,
      Transaction,
      sendAndConfirmTransaction,
    } from "@solana/web3.js";

    import {
      Actions,
      createEd25519AuthorityInfo,
      fetchSwig,
      findSwigPda,
      getAddAuthorityInstructions,
      getCreateSwigInstruction,
      getSignInstructions,
    } from "@swig-wallet/classic";

    import {
      ASSOCIATED_TOKEN_PROGRAM_ID,
      TOKEN_PROGRAM_ID,
      createAssociatedTokenAccount,
      createMint,
      createTransferInstruction,
      getAccount,
      mintTo,
    } from "@solana/spl-token";

    import chalk from "chalk";

    async function createSwigAccount(connection: Connection, user: Keypair) {
      try {
        const id = new Uint8Array(32);
        crypto.getRandomValues(id);
        const swigAddress = findSwigPda(id);
        const rootAuthorityInfo = createEd25519AuthorityInfo(user.publicKey);
        const rootActions = Actions.set().manageAuthority().get();

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

        const transaction = new Transaction().add(createSwigIx);
        const signature = await sendAndConfirmTransaction(connection, transaction, [
          user,
        ]);

        console.log(
          chalk.green("✓ Swig account created at:"),
          chalk.cyan(swigAddress.toBase58()),
        );
        console.log(chalk.blue("Transaction signature:"), chalk.cyan(signature));
        return swigAddress;
      } catch (error) {
        console.error(
          chalk.red("✗ Error creating Swig account:"),
          chalk.red(error),
        );
        throw error;
      }
    }

    async function addNewAuthority(
      connection: Connection,
      rootUser: Keypair,
      newAuthority: Keypair,
      swigAddress: PublicKey,
      actions: any,
      description: string,
    ) {
      try {
        const swig = await fetchSwig(connection, swigAddress);
        const rootRole = swig.findRolesByEd25519SignerPk(rootUser.publicKey)[0];
        if (!rootRole) {
          throw new Error("Root role not found for authority");
        }

        const addAuthorityInstructions = await getAddAuthorityInstructions(
          swig,
          rootRole.id,
          createEd25519AuthorityInfo(newAuthority.publicKey),
          actions,
        );

        const transaction = new Transaction().add(...addAuthorityInstructions);
        await sendAndConfirmTransaction(connection, transaction, [rootUser]);
        console.log(
          chalk.green(`✓ New ${description} authority added:`),
          chalk.cyan(newAuthority.publicKey.toBase58()),
        );
      } catch (error) {
        console.error(
          chalk.red(`✗ Error adding ${description} authority:`),
          chalk.red(error),
        );
        throw error;
      }
    }

    async function displayTokenBalance(
      connection: Connection,
      tokenAccount: PublicKey,
      label: string,
    ) {
      const account = await getAccount(connection, tokenAccount);
      console.log(
        chalk.yellow(`${label} token balance:`),
        chalk.cyan(account.amount.toString()),
      );
    }

    (async () => {
      console.log(
        chalk.blue("🚀 Starting tutorial - Token Authority and Transfers"),
      );

      // Connect to local Solana network
      const connection = new Connection("http://localhost:8899", "confirmed");

      // Create and fund the root user
      const rootUser = Keypair.generate();
      console.log(
        chalk.green("👤 Root user public key:"),
        chalk.cyan(rootUser.publicKey.toBase58()),
      );

      const airdrop = await connection.requestAirdrop(
        rootUser.publicKey,
        100 * LAMPORTS_PER_SOL,
      );
      const blockhash = await connection.getLatestBlockhash();
      await connection.confirmTransaction({
        signature: airdrop,
        blockhash: blockhash.blockhash,
        lastValidBlockHeight: blockhash.lastValidBlockHeight,
      });

      // Create the Swig account
      console.log(chalk.yellow("\n📝 Creating Swig account..."));
      const swigAddress = await createSwigAccount(connection, rootUser);

      // Create token mint
      console.log(chalk.yellow("\n💎 Creating token mint..."));
      const mintAuthority = Keypair.generate();
      const tokenMint = await createMint(
        connection,
        rootUser,
        mintAuthority.publicKey,
        null,
        0,
      );
      console.log(
        chalk.green("✓ Token mint created:"),
        chalk.cyan(tokenMint.toBase58()),
      );

      // Create token accounts
      console.log(chalk.yellow("\n💰 Creating token accounts..."));
      const swigTokenAccount = await createAssociatedTokenAccount(
        connection,
        rootUser,
        tokenMint,
        swigAddress,
        {},
        TOKEN_PROGRAM_ID,
        ASSOCIATED_TOKEN_PROGRAM_ID,
        true,
      );
      console.log(
        chalk.green("✓ Swig token account created:"),
        chalk.cyan(swigTokenAccount.toBase58()),
      );

      const recipientKeypair = Keypair.generate();
      const recipientTokenAccount = await createAssociatedTokenAccount(
        connection,
        rootUser,
        tokenMint,
        recipientKeypair.publicKey,
      );
      console.log(
        chalk.green("✓ Recipient token account created:"),
        chalk.cyan(recipientTokenAccount.toBase58()),
      );

      // Mint initial tokens to Swig account
      console.log(chalk.yellow("\n🏦 Minting tokens to Swig account..."));
      await mintTo(
        connection,
        rootUser,
        tokenMint,
        swigTokenAccount,
        mintAuthority,
        10,
      );
      await displayTokenBalance(connection, swigTokenAccount, "Swig");
      await displayTokenBalance(connection, recipientTokenAccount, "Recipient");

      // Create token authority with permission to send exactly 10 tokens
      const tokenAuthority = Keypair.generate();
      console.log(
        chalk.green("\n👥 Token authority public key:"),
        chalk.cyan(tokenAuthority.publicKey.toBase58()),
      );
      await connection.requestAirdrop(
        tokenAuthority.publicKey,
        100 * LAMPORTS_PER_SOL,
      );
      console.log(chalk.yellow("\n🔑 Adding token authority..."));
      const tokenActions = Actions.set()
        .tokenLimit({ mint: tokenMint, amount: BigInt(10) })
        .get();
      await addNewAuthority(
        connection,
        rootUser,
        tokenAuthority,
        swigAddress,
        tokenActions,
        "token",
      );

      // Add some delay to ensure the authority is added
      await new Promise((resolve) => setTimeout(resolve, 2000));

      // First transfer - should succeed
      console.log(chalk.yellow("\n💸 Attempting first transfer of 10 tokens..."));
      try {
        const swig = await fetchSwig(connection, swigAddress);
        const tokenRole = swig.findRolesByEd25519SignerPk(
          tokenAuthority.publicKey,
        )[0];

        const transferIx = createTransferInstruction(
          swigTokenAccount,
          recipientTokenAccount,
          swigAddress,
          BigInt(10),
        );

        const signedTransfer = await signInstruction(
          tokenRole,
          tokenAuthority.publicKey,
          [transferIx],
        );

        const transaction = new Transaction().add(signedTransfer);
        await sendAndConfirmTransaction(connection, transaction, [tokenAuthority]);
        console.log(chalk.green("✓ First transfer successful!"));
        await displayTokenBalance(connection, swigTokenAccount, "Swig");
        await displayTokenBalance(connection, recipientTokenAccount, "Recipient");
      } catch (error) {
        console.error(chalk.red("✗ First transfer failed:"), chalk.red(error));
      }

      // Second transfer - should fail
      console.log(chalk.yellow("\n💸 Attempting second transfer (should fail)..."));
      try {
        const swig = await fetchSwig(connection, swigAddress);
        const tokenRole = swig.findRolesByEd25519SignerPk(
          tokenAuthority.publicKey,
        )[0];

        const transferIx = createTransferInstruction(
          swigTokenAccount,
          recipientTokenAccount,
          swigAddress,
          BigInt(10),
        );

        const signedTransfer = await signInstruction(
          tokenRole,
          tokenAuthority.publicKey,
          [transferIx],
        );

        const transaction = new Transaction().add(signedTransfer);
        await sendAndConfirmTransaction(connection, transaction, [tokenAuthority], {
          skipPreflight: true,
        });
        console.error(chalk.red("✗ Second transfer unexpectedly succeeded!"));
      } catch {
        console.log(
          chalk.green("✓ Second transfer failed as expected:"),
          "Authority has no remaining token allowance",
        );
      }

      await displayTokenBalance(connection, swigTokenAccount, "Final Swig");
      await displayTokenBalance(
        connection,
        recipientTokenAccount,
        "Final Recipient",
      );

      console.log(chalk.green("\n✨ Tutorial completed successfully!"));
      console.log(
        chalk.yellow("🔍 Check out your transaction on Solana Explorer:"),
      );
      console.log(
        chalk.cyan(
          `https://explorer.solana.com/address/${swigAddress}?cluster=custom&customUrl=http%3A%2F%2Flocalhost%3A8899`,
        ),
      );
    })();
    ```
  </Tab>

  <Tab title="Kit">
    ```typescript theme={null}
    import {
      createSolanaRpc,
      createSolanaRpcSubscriptions,
      generateKeyPairSigner,
      getSignatureFromTransaction,
      lamports,
      pipe,
      sendAndConfirmTransactionFactory,
      signTransactionMessageWithSigners,
      createTransactionMessage,
      setTransactionMessageFeePayerSigner,
      setTransactionMessageLifetimeUsingBlockhash,
      appendTransactionMessageInstructions,
      addSignersToTransactionMessage,
      type IInstruction,
      type KeyPairSigner,
    } from '@solana/kit';

    import {
      Actions,
      createEd25519AuthorityInfo,
      fetchSwig,
      findSwigPda,
      getAddAuthorityInstructions,
      getCreateSwigInstruction,
      getSignInstructions,
    } from '@swig-wallet/kit';

    import {
      TOKEN_2022_PROGRAM_ADDRESS,
      findAssociatedTokenPda,
      getCreateAssociatedTokenInstructionAsync,
      getInitializeMintInstruction,
      getMintSize,
      getMintToCheckedInstruction,
      getTransferCheckedInstruction,
    } from '@solana-program/token-2022';

    import { getCreateAccountInstruction } from '@solana-program/system';

    import chalk from 'chalk';
    import { sleepSync } from 'bun';

    function randomBytes(length: number): Uint8Array {
      const arr = new Uint8Array(length);
      crypto.getRandomValues(arr);
      return arr;
    }

    async function sendTransaction(
      instructions: IInstruction[],
      payer: KeyPairSigner,
      signers: KeyPairSigner[] = []
    ): Promise<string> {
      const { value: latestBlockhash } = await rpc.getLatestBlockhash().send();
      const txMsg = pipe(
        createTransactionMessage({ version: 0 }),
        (tx) => setTransactionMessageFeePayerSigner(payer, tx),
        (tx) => setTransactionMessageLifetimeUsingBlockhash(latestBlockhash, tx),
        (tx) => appendTransactionMessageInstructions(instructions, tx),
        (tx) => addSignersToTransactionMessage(signers, tx)
      );

      const signedTx = await signTransactionMessageWithSigners(txMsg);
      await sendAndConfirmTransactionFactory({ rpc, rpcSubscriptions })(signedTx, {
        commitment: 'confirmed',
      });
      return getSignatureFromTransaction(signedTx).toString();
    }

    const rpc = createSolanaRpc('http://localhost:8899');
    const rpcSubscriptions = createSolanaRpcSubscriptions('ws://localhost:8900');

    (async () => {
      console.log(chalk.blue('🚀 Starting tutorial - Token Authority and Transfers (Kit Style)'));

      const rootUser = await generateKeyPairSigner();
      await rpc.requestAirdrop(rootUser.address, lamports(100n * 1_000_000_000n)).send();
      sleepSync(2000);
      console.log(chalk.green('👤 Root user public key:'), chalk.cyan(rootUser.address.toString()));

      const id = randomBytes(32);
      const swigAddress = await findSwigPda(id);
      const rootAuthorityInfo = createEd25519AuthorityInfo(rootUser.address);
      const rootActions = Actions.set().manageAuthority().get();

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

      await sendTransaction([createSwigIx], rootUser);
      console.log(chalk.green('✓ Swig account created at:'), chalk.cyan(swigAddress.toString()));

      await rpc.requestAirdrop(swigAddress, lamports(1n)).send();
      sleepSync(2000);
      console.log(chalk.green('✓ Airdropped 1 SOL to Swig account'));

      const mint = await generateKeyPairSigner();
      const mintAuthority = rootUser;
      const decimals = 0;

      const rent = await rpc.getMinimumBalanceForRentExemption(BigInt(getMintSize())).send();

      const createMintAccountIx = getCreateAccountInstruction({
        payer: mintAuthority,
        newAccount: mint,
        lamports: rent,
        space: BigInt(getMintSize()),
        programAddress: TOKEN_2022_PROGRAM_ADDRESS,
      });

      const initMintIx = getInitializeMintInstruction({
        mint: mint.address,
        decimals,
        mintAuthority: mintAuthority.address,
      });

      const [swigATA] = await findAssociatedTokenPda({
        mint: mint.address,
        owner: swigAddress,
        tokenProgram: TOKEN_2022_PROGRAM_ADDRESS,
      });

      const createSwigATAIx = await getCreateAssociatedTokenInstructionAsync({
        payer: mintAuthority,
        mint: mint.address,
        owner: swigAddress,
      });

      const mintToSwigIx = await getMintToCheckedInstruction({
        mint: mint.address,
        token: swigATA,
        mintAuthority,
        amount: 10n,
        decimals,
      });

      await sendTransaction(
        [createMintAccountIx, initMintIx, createSwigATAIx, mintToSwigIx],
        mintAuthority,
        [mint]
      );
      console.log(chalk.green('✓ Token mint and Swig ATA created and funded'));

      const recipient = await generateKeyPairSigner();
      const [recipientATA] = await findAssociatedTokenPda({
        mint: mint.address,
        owner: recipient.address,
        tokenProgram: TOKEN_2022_PROGRAM_ADDRESS,
      });

      const createRecipientATAIx = await getCreateAssociatedTokenInstructionAsync({
        payer: rootUser,
        mint: mint.address,
        owner: recipient.address,
      });

      await sendTransaction([createRecipientATAIx], rootUser);
      console.log(chalk.green('✓ Recipient ATA created'));

      const tokenAuthority = await generateKeyPairSigner();
      await rpc.requestAirdrop(tokenAuthority.address, lamports(1n)).send();
      sleepSync(2000);

      const tokenActions = Actions.set()
        .tokenLimit({ mint: mint.address, amount: 10n })
        .get();

      const swig = await fetchSwig(rpc, swigAddress);
      const rootRole = swig.findRolesByEd25519SignerPk(rootUser.address)[0];

      const addAuthorityIxs = await getAddAuthorityInstructions(
        swig,
        rootRole.id,
        createEd25519AuthorityInfo(tokenAuthority.address),
        tokenActions
      );

      await sendTransaction(addAuthorityIxs, rootUser);
      console.log(chalk.green('✓ Token authority added'));

      //check how much sol the swig has
      const swigBalance = await rpc.getBalance(swigAddress).send();
      console.log(chalk.green('✓ Swig account balance:'), chalk.cyan(swigBalance.value.toString()));

      // Add balance checks for Swig ATA and Recipient ATA
      const swigATABalance = await rpc.getTokenAccountBalance(swigATA).send();
      console.log(chalk.green('✓ Swig ATA balance:'), chalk.cyan(swigATABalance.value.amount));

      const recipientATABalance = await rpc.getTokenAccountBalance(recipientATA).send();
      console.log(chalk.green('✓ Recipient ATA balance:'), chalk.cyan(recipientATABalance.value.amount));

      // ❌ Second transfer (should fail)
      try {
        const swigLatest = await fetchSwig(rpc, swigAddress);
        const role = swigLatest.findRolesByEd25519SignerPk(tokenAuthority.address)[0];

        const transferAgain = getTransferCheckedInstruction({
          source: swigATA,
          destination: recipientATA,
          mint: mint.address,
          amount: 10n,
          decimals,
          authority: swigAddress,
        });

        const signed = await getSignInstructions(swigLatest, role.id, [transferAgain]);
        await sendTransaction(signed, tokenAuthority);
        console.error(chalk.red('✗ Second transfer unexpectedly succeeded!'));
      } catch {
        console.log(chalk.green('✓ Second transfer failed as expected (no allowance left)'));
      }

      console.log(chalk.green('\n✨ Tutorial completed successfully!'));
      console.log(
        chalk.yellow('🔍 View your Swig on Explorer:'),
        chalk.cyan(
          `https://explorer.solana.com/address/${swigAddress}?cluster=custom&customUrl=http%3A%2F%2Flocalhost%3A8899`
        )
      );
    })();
    ```
  </Tab>
</Tabs>

Let's break down how signing works with Swig.

## 1. Fetch the Swig Account

<Tabs>
  <Tab title="Classic">
    ```typescript theme={null}
    const swig = await fetchSwig(connection, swigAddress);
    ```
  </Tab>

  <Tab title="Kit">
    ```typescript theme={null}
    const swig = await fetchSwig(rpc, swigAddress);
    ```
  </Tab>
</Tabs>

First, we need to fetch the current state of our Swig account. This contains all the roles and their permissions that we set up in the previous tutorials.

## 2. Find the Appropriate Role

<Tabs>
  <Tab title="Classic">
    ```typescript theme={null}
    const tokenRole = swig.findRolesByEd25519SignerPk(tokenAuthority.publicKey)[0];
    ```
  </Tab>

  <Tab title="Kit">
    ```typescript theme={null}
    const role = swig.findRolesByEd25519SignerPk(tokenAuthority.address)[0];
    ```
  </Tab>
</Tabs>

We locate the role associated with our token authority. Remember from the previous tutorial that this role was created with specific token transfer limits.

> 💡 A single authority can have multiple roles. Always make sure you're using the correct role for your intended action.

## 3. Create the Instruction

<Tabs>
  <Tab title="Classic">
    ```typescript theme={null}
    const transferIx = createTransferInstruction(
      swigTokenAccount,
      recipientTokenAccount,
      swigAddress,
      BigInt(10),
    );
    ```
  </Tab>

  <Tab title="Kit">
    ```typescript theme={null}
    const transferAgain = getTransferCheckedInstruction({
      source: swigATA,
      destination: recipientATA,
      mint: mint.address,
      amount: 10n,
      decimals,
      authority: swigAddress,
    });
    ```
  </Tab>
</Tabs>

Create the instruction that needs to be signed. In this case, it's a token transfer instruction, but Swig can sign any type of instruction as long as the role has the appropriate permissions.

## 4. Sign the Instruction

<Tabs>
  <Tab title="Classic">
    ```typescript theme={null}
    const signedTransferInstructions = await getSignInstructions(
      swig,
      tokenRole.id,
      [transferIx],
    );
    ```
  </Tab>

  <Tab title="Kit">
    ```typescript theme={null}
    const signed = await getSignInstructions(swigLatest, role.id, [transferAgain]);
    ```
  </Tab>
</Tabs>

This is where the magic happens. The `getSignInstructions` function:

1. Verifies that the role has permission to sign this type of instruction
2. Creates the necessary signing instructions
3. Wraps the original instruction with Swig's signing logic

> 🔒 Swig validates both the authority type and action permissions at this stage

## 5. Build and Send the Transaction

<Tabs>
  <Tab title="Classic">
    ```typescript theme={null}
    const transaction = new Transaction().add(...signedTransferInstructions);
    await sendAndConfirmTransaction(connection, transaction, [tokenAuthority]);
    ```
  </Tab>

  <Tab title="Kit">
    ```typescript theme={null}
    await sendTransaction(signed, tokenAuthority);
    ```
  </Tab>
</Tabs>

Finally, we build the transaction with our signed instructions and send it to the network. Note that the transaction still needs to be signed by the authority's keypair because they're the one paying for the transaction fees.

## Understanding Signature Verification

When the transaction reaches the Solana network, the Swig program will:

1. Extract the original instruction
2. Verify the authority's signature
3. Check that the role's permissions allow this action
4. Execute the instruction if all checks pass

> 🧠 This multi-step verification ensures that only authorized actions are performed

## Ready to try it?

Make sure you have:

1. Completed the previous tutorials
2. Have a running validator (`bun start-validator`)
3. Created a Swig account with appropriate authorities

Then run:

```bash theme={null}
bun run ./tutorial/tutorial-3.ts
```

The link at the end of the tutorial will take you to the swig on the Solana Explorer. You will see multiple transactions and there should be one failed which shows the negative case.


# Use Cases: Customers
Source: https://build.onswig.com/use-case-customers



Swig is built for developers. Our smart wallet tooling is allowing developers to quickly unlock both fundamental and advanced functionality for their end-users. We’re early, but we’re already powering a diverse set of use cases across payments, dApps, AI, cross-chain, and many more.

## **Payments**

Why build your payments use case on Swig:

* **Subscriptions:** Enable automatic, on-chain subscription payments that are configurable to your required payment cadence.
* **Pre-Set Spending Conditions:** Ensure that your users never get charged more than the amounts they expect to get charged.
* **Payment Streaming:** Enable micropayment streams of any kind.
* **Payment Speed:** Authorize transactions in less than 800 milliseconds with Swig.
* **Configurable Payment Holds:** Allows you to configure settlement times on card payments based on your card’s needs. Set settlements to be real-time, on hold for 24 hours, or any other amount of time - whatever is required for your use case.

## **dApps**

Why build your dApp on Swig:

* **Granular Permissions:** Enables users to give your app specific permissions without giving you access to their whole wallet, which allows you to create more powerful experiences for your users with the permissions granted to the app while staying non-custodial.
* **Configurable & Automatic Transactions:** Powers functionality like automatic trading strategies, conditional transactions based on chain events, dollar-cost averaging, continuous transactions, and much more.
* **Session Keys:** Allows users to just approve once during a defined time period while using your app. Avoids the UX frictions of constant manual signing.
* **Gasless Transactions:** Integrate Swig’s paymaster to eliminate UX friction by covering gas fees for your users or enable them to pay gas fees with non-native tokens.
* **Social Sign In & Recovery:** Onboard non-crypto and crypto-native users without frictions associated with traditional wallet onboarding and seed recovery concerns.
* **Chain Abstraction:** Enables your app to operate across multiple SVM chains without UX frictions since users can operate across SVM chains with one Swig wallet.

<video />

## **AI**

Why build your AI use case on Swig:

* **AI Chat:** Easily create AI-powered chat-to-action functionality within your app that enables users conduct transactions in your app experience via a chat function. Users can type things like "buy 10 SOL next time the price drops below \$100" and your app handles the rest with Swig.
* **AI Swarms:** Use Swig’s role-based permissions architecture to enable AI swarm use cases for any app type. With Swig, you can configure multiple agents to each have different permissions and have them work together based on conditional logic.
* **Frictionless AI:** Leveraging session keys, agents can seamlessly execute several transactions within a defined period without needing to stop for constant approvals.
* **Much More...** the functionality that Swig offers on-chain agents can power an endless possibility of features. We encourage builders to get creative and let us know what you were able to build on Swig.

## **Cross-Chain**

Why “add Solana” to your app using Swig:

* **Sign SVM Transactions With EVM Keys:** Building on Swig allows your users to sign SVM transactions during their app experience without needing to leave their EVM wallet. This allows your app and your users to benefit from the power of Solana without creating any UX friction.
* **"Add Solana":** For apps that are expanding their chain support to Solana, building their Solana use case on Swig from the start has allowed them to ensure the most robust Solana experience for their users while avoiding development headaches that come with working on an unfamiliar chain. Our docs can be exported as an MCP server so that non-Solana native developers can easily understand Swig and build powerful Solana use cases for their users.
* **UX Parity Across Chains:** If your app is multi-chain, you are likely using EVM smart wallet tools to power advanced experiences for your users when they interact with EVM protocols. But until now, you haven't been able to provide them with experience parity when they interact with SVM protocols in your app. With Swig's smart wallet functionality, you can close that parity gap to ensure your users have universal experiences across EVM and SVM chains.

## **And more...**

Swig’s primitives allow for an endless number of possibilities across any use case. In addition to payments, dApps, AI, and cross-chain use cases, Swig can power use cases such as custodians adding hot wallet functionality to their custody stack, exchanges building unique on-chain trading experiences, gaming apps reducing in-game UX frictions, and many more.

**We believe some of the most powerful use cases built on Swig have not even been imagined yet. If you are a developer and are interested in building something new on Solana, we encourage you to play around on Swig and see what Swig can enable you to create.**


# Use Cases: Partners
Source: https://build.onswig.com/use-case-partners



Swig’s smart wallet tooling helps embedded wallets, wallets, SVM L2s, and other partners better service their ecosystem of developers, which in turn helps them build better use cases for their users.

## **Wallets & Embedded Wallets**

Swig is a great fit as a partner to wallets & embedded wallets to help solve the needs of their developers:

* **Add Solana Smart Wallet Tooling:** Expose SVM smart wallet tooling to your ecosystem of developers building on your embedded wallet so that your platform continues to be where they build across multiple chains.
* **Custom Auth Flows:** Build custom authentication flows by combining Swig’s wallet SDK with your embedded wallet for your developers to leverage as they build.
* **Additional Auth Types:** For MPC wallets, your developers can use your wallet and leverage multiple different auth types beyond just MPC when combined with Swig.
* **Much More...** the functionality that Swig offers combined with your wallet can provide boundless benefits to developers and allow you to grow your ecosystem.

Let's work together to empower developers building Solana use cases.

<video />

## **SVM L2s**

Swig can help SVM L2s build a robust ecosystem:

* **Build Better Apps:** Swig's smart wallet functionality combined with the benefits of SVM offer developers with the tooling to create the most compelling apps. Ensuring your ecosystem of developers are building on Swig will set your chain up well for user adoption growth as users will be drawn to apps that have the advanced functionality that building on Swig can create.
* **Reduce Onboarding Frictions:** Swig's cross-chain functionality enables developers to build apps that operate across multiple SVM chains without UX frictions since users can operate across SVM chains with one Swig wallet. This means that developers building on Swig will have an easier time bringing users to your chain.

Let's work together to bring adoption to your chain.

## **And more...**

Swig’s primitives allow for an endless number of possibilities across any use case. We are powering use cases across payments, dApps, AI, cross-chain, custodians, exchanges, gaming apps and more. If you are looking to grow your ecosystems of developers and users, it’s very likely that partnering with Swig can help accelerate that.

Get in touch with our team [here](https://forms.gle/VmQSNmLFhVm8AZGz8).