> ## Documentation Index
> Fetch the complete documentation index at: https://developers.squads.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Abstract Transaction Fees

> Sponsor gas fees for standard Solana wallet transactions using Grid paymaster

The Gas Abstraction endpoint enables fee sponsorship for standard Solana wallet transactions through the Grid paymaster system. This service removes the requirement for users to hold SOL tokens for transaction fees, creating a seamless user experience.

> [!WARNING]
>
> This endpoint is **exclusively for standard Solana wallets** (keypair-based
> accounts). For Squads smart accounts with built-in gas abstraction, see [Grid
> v1 Cost Efficiency](https://developers.squads.so/grid/v1/accounts/cost-efficiency.md).

## How It Works

The gas abstraction process follows these steps:

1. **Transaction Submission**: Send your unsigned, base64-encoded transaction to the endpoint
2. **Fee Calculation**: The paymaster computes the required fees in your specified currency (defaults to USDC)
3. **Paymaster Signing**: The paymaster adds its signature to sponsor the fees
4. **User Signing**: Add the user's signature to the paymaster-signed transaction
5. **Blockchain Submission**: Submit the fully signed transaction to Solana

## Implementation Guide

**1. Prepare Your Unsigned Transaction**

Create your versioned transaction without signing it:

```javascript theme={null}
import {
  VersionedTransaction,
  TransactionMessage,
  SystemProgram,
  PublicKey,
  Connection,
  LAMPORTS_PER_SOL,
} from "@solana/web3.js";

const connection = new Connection("https://api.mainnet-beta.solana.com");

// Create transaction instructions (example: SOL transfer)
const transferInstruction = SystemProgram.transfer({
  fromPubkey: senderPublicKey,
  toPubkey: recipientPublicKey,
  lamports: 0.1 * LAMPORTS_PER_SOL,
});

// Get recent blockhash and build transaction message
const { blockhash } = await connection.getLatestBlockhash();
const messageV0 = new TransactionMessage({
  payerKey: senderPublicKey,
  recentBlockhash: blockhash,
  instructions: [transferInstruction],
}).compileToV0Message();

// Create versioned transaction (unsigned)
const transaction = new VersionedTransaction(messageV0);

// Serialize to base64
const serializedTransaction = Buffer.from(
  transaction.serialize()
).toString("base64");
```

**2. Submit to Gas Abstraction API**

Send your unsigned transaction to the endpoint:

```javascript theme={null}
const response = await fetch(
  "https://grid.squads.xyz/api/v0/grid/transactions/eoa/gas-abstraction",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer YOUR_API_KEY",
      "X-Grid-Environment": "production", // or 'sandbox' for devnet
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      transaction: serializedTransaction,
    }),
  }
);

const result = await response.json();

// Review fee information
console.log(`Fee: ${result.fee.amount_decimal} ${result.fee.currency}`);
console.log(
  `SOL equivalent: ${result.fee.sol_equivalent.amount_decimal} SOL`
);
```

**3. Sign and Submit to Blockchain**

Deserialize the paymaster-signed transaction, add the user's signature, and submit:

```javascript theme={null}
import { VersionedTransaction } from "@solana/web3.js";

// Decode the paymaster-signed transaction
const signedTransactionBuffer = Buffer.from(result.transaction, "base64");
const transaction = VersionedTransaction.deserialize(
  signedTransactionBuffer
);

// Add user's signature
transaction.sign([userKeypair]);

// Submit to blockchain
const signature = await connection.sendTransaction(transaction);
console.log("Transaction signature:", signature);

// Confirm transaction
const confirmation = await connection.confirmTransaction(signature);
console.log(
  "Status:",
  confirmation.value.err ? "Failed" : "Confirmed"
);
```

## Fee Structure

### Fee Calculation

The total fee consists of:

* **Compute Units**: Based on transaction complexity and computational requirements
* **Rent Fees**: For account creation or rent-exempt balance requirements
* **Currency Conversion**: Fees quoted in your specified currency (default: USDC)

### Billing Details

* **Sandbox Environment**: Devnet transactions are processed but not billed
* **Production Environment**: Mainnet transactions are recorded and billed according to your Grid API agreement
* **Fee Components**: Transaction, priority, and rent fees are included in billing

## Custom Identifiers

Use the optional `customIdentifier` query parameter to group and track related transactions:

```javascript theme={null}
const response = await fetch(
  "https://grid.squads.xyz/api/v0/grid/transactions/eoa/gas-abstraction?customIdentifier=user-123-session-abc",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer YOUR_API_KEY",
      "X-Grid-Environment": "production",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      transaction: serializedTransaction,
    }),
  }
);
```

Custom identifiers enable you to:

* Group transactions by user, session, or feature
* Query fee history by identifier
* Track usage patterns and costs per category

## Transaction Validation

Transactions must:

* Be valid Solana transactions that can be simulated successfully
* Use versioned transaction format
* Be properly serialized to base64
* Not be pre-signed

## Error Handling

Common error scenarios:

### Invalid Transaction Format

```json theme={null}
{
  "code": "INVALID_TRANSACTION",
  "message": "tried to parse invalid transaction"
}
```

**Solution**: Verify your transaction is properly serialized and base64-encoded.

### Invalid Environment Header

```json theme={null}
{
  "code": "INVALID_ENVIRONMENT",
  "message": "Environment must be either 'sandbox' or 'production'"
}
```

**Solution**: Ensure `X-Grid-Environment` header is set to either `sandbox` or `production`.

### Service Unavailable

```json theme={null}
{
  "code": "SERVICE_UNAVAILABLE",
  "message": "The service is temporarily unavailable. Please try again."
}
```

**Solution**: Implement retry logic with exponential backoff.

## Security Best Practices

1. **API Key Protection**: Never expose your Grid API key in client-side code or public repositories
2. **Environment Separation**: Use sandbox for testing, production only for live transactions
3. **Transaction Verification**: Always validate the returned signed transaction matches your intent
4. **Fee Monitoring**: Implement alerts for unexpected fee spikes
5. **Rate Limiting**: Implement appropriate rate limiting to avoid overwhelming the API


## OpenAPI

````yaml POST /transactions/eoa/gas-abstraction
openapi: 3.1.0
info:
  title: Grid API
  description: Grid API Documentation
  license:
    name: ''
  version: 1.0.0
servers:
  - url: https://grid.squads.xyz/api/v0/grid
    description: Production Server
security:
  - bearerAuth: []
tags:
  - name: smart-accounts
    description: Smart Accounts
paths:
  /transactions/eoa/gas-abstraction:
    post:
      tags:
        - EOA Transactions
      summary: Abstract gas fees for EOA transactions
      description: >
        Sponsor gas fees for externally owned account (EOA) transactions using
        the paymaster.

        This endpoint is specifically designed for EOA wallets and is separate
        from smart account gas abstraction.

        The paymaster will sponsor the transaction fees and return a signed
        transaction ready for submission.
      operationId: abstract_eoa_gas_fees
      parameters:
        - name: X-Grid-Environment
          in: header
          description: The environment you're using. Can be `sandbox` or `production`.
          required: true
          schema:
            type: string
        - name: customIdentifier
          in: query
          description: Optional custom identifier for tracking purposes
          required: false
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EoaGasAbstractionRequest'
        required: true
      responses:
        '200':
          description: Transaction successfully processed with abstracted fees
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EoaGasAbstractionResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GridError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GridError'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GridError'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GridError'
      security:
        - bearerAuth: []
components:
  schemas:
    EoaGasAbstractionRequest:
      type: object
      required:
        - transaction
      properties:
        transaction:
          type: string
          description: Base64-encoded transaction to process for fee abstraction
    EoaGasAbstractionResponse:
      type: object
      required:
        - transaction
        - fee
      properties:
        transaction:
          type: string
          description: >-
            Base64-encoded signed transaction ready for submission to the
            blockchain
        fee:
          $ref: '#/components/schemas/FinalizedFees'
          description: Detailed fee breakdown for the transaction
    GridError:
      type: object
      required:
        - message
        - details
        - timestamp
      properties:
        details:
          type: array
          items:
            $ref: '#/components/schemas/Detail'
        message:
          type: string
        timestamp:
          type: string
    FinalizedFees:
      type: object
      required:
        - amount
        - amount_decimal
        - currency
        - sol_equivalent
      properties:
        amount:
          type: string
          description: >-
            Fee amount in smallest currency unit (e.g., cents for USD, lamports
            for SOL)
        amount_decimal:
          type: string
          description: Human-readable decimal representation of the fee amount
        currency:
          $ref: '#/components/schemas/Currency'
          description: Currency used for the fee calculation
        sol_equivalent:
          $ref: '#/components/schemas/SolEquivalent'
          description: SOL equivalent value of the fee for reference
    Detail:
      type: object
      required:
        - field
        - code
        - message
      properties:
        code:
          type: string
        field:
          type: string
        message:
          type: string
    Currency:
      type: string
      enum:
        - usd
        - eur
        - mxn
        - usdc
        - usdt
        - usdb
        - dai
        - pyusd
        - eurc
    SolEquivalent:
      type: object
      required:
        - amount
        - amount_decimal
      properties:
        amount:
          type: string
          description: SOL amount in lamports (smallest SOL unit)
        amount_decimal:
          type: string
          description: Human-readable decimal SOL amount
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: API Key for authentication

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.