> ## 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.

# Query Fee Records

> Retrieve historical gas abstraction fee records with pagination and filtering

The Query Gas Abstraction Fees endpoint provides access to historical fee records for transactions processed through the gas abstraction system for standard Solana wallets. Use this endpoint to track billing, analyze usage patterns, and monitor costs.

> [!WARNING]
>
> This endpoint retrieves **only standard Solana wallet** gas abstraction fee
> records. For Squads smart accounts with built-in gas abstraction, see [Grid's
> Smart Accounts](https://developers.squads.so/grid/v1/accounts/introduction.md).

## Use Cases

This endpoint enables you to:

* **Track Billing History**: Review all gas abstraction fees for accounting and reconciliation
* **Filter by Identifier**: Group and analyze transactions by custom identifier
* **Analyze Usage Patterns**: Understand fee trends over time
* **Monitor Costs**: Track spending across different features or users
* **Audit Transactions**: Verify fee records match your expectations

## Usage Examples

### Basic Query

Retrieve the first 50 fee records:

```javascript theme={null}
const customIdentifier = "user-123-session-abc";

const response = await fetch(
  `https://grid.squads.xyz/api/v0/grid/transactions/eoa/gas-abstraction?customIdentifier=${customIdentifier}`,
  {
    headers: {
      Authorization: "Bearer YOUR_API_KEY",
      "X-Grid-Environment": "production",
    },
  }
);

const data = await response.json();
console.log(`Total records: ${data.data.pagination.total_count}`);
console.log(`Current page: ${data.data.fees.length} records`);
```

### Paginated Retrieval

Fetch all fee records with pagination:

```javascript theme={null}
async function getAllFeeRecords(customIdentifier) {
  const allFees = [];
  let page = 1;
  const limit = 100;

  while (true) {
    const response = await fetch(
      `https://grid.squads.xyz/api/v0/grid/transactions/eoa/gas-abstraction?customIdentifier=${customIdentifier}&page=${page}&limit=${limit}`,
      {
        headers: {
          Authorization: "Bearer YOUR_API_KEY",
          "X-Grid-Environment": "production",
        },
      }
    );

    const data = await response.json();
    allFees.push(...data.data.fees);

    if (!data.data.pagination.has_next_page) break;
    page++;
  }

  return allFees;
}

// Usage
const fees = await getAllFeeRecords("user-123-session-abc");
console.log(`Retrieved ${fees.length} total fee records`);
```

### Date Range Filtering

Query fees within a specific time period:

```javascript theme={null}
const customId = "user-123-session-abc";
const startDate = "2024-01-01T00:00:00Z";
const endDate = "2024-01-31T23:59:59Z";

const params = new URLSearchParams({
  customIdentifier: customId,
  startDate,
  endDate,
  limit: "100",
});

const response = await fetch(
  `https://grid.squads.xyz/api/v0/grid/transactions/eoa/gas-abstraction?${params}`,
  {
    headers: {
      Authorization: "Bearer YOUR_API_KEY",
      "X-Grid-Environment": "production",
    },
  }
);

const data = await response.json();
console.log(`January 2024: ${data.data.fees.length} transactions`);
```

### Cost Analysis

Calculate total fees for a period:

```javascript theme={null}
const customId = "user-123-session-abc";
const startDate = "2024-01-01T00:00:00Z";
const endDate = "2024-01-31T23:59:59Z";

const params = new URLSearchParams({
  customIdentifier: customId,
  startDate,
  endDate,
});

const response = await fetch(
  `https://grid.squads.xyz/api/v0/grid/transactions/eoa/gas-abstraction?${params}`,
  {
    headers: {
      Authorization: "Bearer YOUR_API_KEY",
      "X-Grid-Environment": "production",
    },
  }
);

const data = await response.json();

// Calculate total costs
const totalCosts = data.data.fees.reduce((sum, fee) => {
  const txFee = parseFloat(fee.tx_fee_in_currency || "0");
  const rentFee = parseFloat(fee.rent_fee_in_currency || "0");
  return sum + txFee + rentFee;
}, 0);

console.log(`Total fees for January 2024: $${totalCosts.toFixed(2)}`);

// Calculate average transaction fee
const avgFee = totalCosts / data.data.fees.length;
console.log(`Average fee per transaction: $${avgFee.toFixed(4)}`);
```

## Pagination Information

The `pagination` object provides navigation details:

* **page**: Current page number
* **limit**: Items per page
* **total\_count**: Total number of records matching the query
* **has\_next\_page**: Whether additional pages are available

### Response Headers

Pagination metadata is also available in response headers:

* `X-Total-Count`: Total number of records
* `X-Page`: Current page number
* `X-Limit`: Current limit value
* `X-Next-Page`: Next page number (if available)

## Best Practices

### Pagination Strategy

1. **Use appropriate page sizes**: Start with 50-100 records per page
2. **Implement progressive loading**: Fetch additional pages as needed
3. **Cache results**: Store frequently accessed data to reduce API calls
4. **Handle pagination gracefully**: Check `has_next_page` before fetching more

### Performance Optimization

1. **Filter by date range**: Narrow queries to specific time periods
2. **Use custom identifiers**: Group related transactions for easier filtering
3. **Implement retry logic**: Handle transient errors with exponential backoff
4. **Monitor rate limits**: Space out requests to avoid throttling

### Cost Monitoring

1. **Set up alerts**: Monitor for unexpected fee spikes
2. **Regular audits**: Review fee records periodically
3. **Budget tracking**: Compare actual vs expected costs
4. **Usage analytics**: Identify high-cost features or users

## Data Retention

* **Retention Period**: Fee records are retained indefinitely for billing and audit purposes
* **Historical Access**: All records remain accessible from when you first started using the service
* **Data Accuracy**: Records reflect the exact fees charged at transaction time

## Error Handling

### Invalid Custom Identifier

```json theme={null}
{
  "code": "INVALID_CUSTOM_IDENTIFIER",
  "message": "Custom identifier must be a valid UUID"
}
```

**Solution**: Ensure your custom identifier is a properly formatted UUID string.

### Invalid Timestamp Format

```json theme={null}
{
  "code": "INVALID_TIMESTAMP",
  "message": "Timestamp must be in ISO 8601 format"
}
```

**Solution**: Use ISO 8601 format for date parameters (e.g., "2024-01-01T00:00:00Z").

### Invalid Pagination Parameters

```json theme={null}
{
  "code": "INVALID_PAGINATION",
  "message": "Limit must be between 1 and 1000"
}
```

**Solution**: Ensure `limit` is within the valid range (1-1000) and `offset` is non-negative.


## OpenAPI

````yaml GET /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:
    get:
      tags:
        - EOA Transactions
      summary: Query EOA gas abstraction fee records
      description: Retrieve historical gas abstraction fee records for EOA transactions
      operationId: query_eoa_gas_abstraction_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: Filter by custom identifier
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successfully retrieved fee records
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EoaGasAbstractionQueryResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GridError'
        '401':
          description: Unauthorized
          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:
    EoaGasAbstractionQueryResponse:
      type: object
      required:
        - fees
        - pagination
      properties:
        fees:
          type: array
          items:
            $ref: '#/components/schemas/GasAbstractionFeeRecord'
          description: List of gas abstraction fee records
        pagination:
          $ref: '#/components/schemas/PaginationInfo'
          description: Pagination information for the response
    GridError:
      type: object
      required:
        - message
        - details
        - timestamp
      properties:
        details:
          type: array
          items:
            $ref: '#/components/schemas/Detail'
        message:
          type: string
        timestamp:
          type: string
    GasAbstractionFeeRecord:
      type: object
      required:
        - id
        - client_id
        - custom_identifier
        - currency
        - created_at
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the fee record
        client_id:
          type: string
          format: uuid
          description: Client ID associated with the transaction
        custom_identifier:
          type: string
          format: uuid
          description: Custom identifier provided during the transaction
        confirmation_status:
          type: string
          description: Status of the transaction confirmation
        tx_fee_lamports:
          type: string
          nullable: true
          description: Transaction fee in lamports
        tx_fee_in_currency:
          type: string
          nullable: true
          description: Transaction fee converted to the specified currency
        rent_fee_lamports:
          type: string
          nullable: true
          description: Rent fee in lamports
        rent_fee_in_currency:
          type: string
          nullable: true
          description: Rent fee converted to the specified currency
        currency:
          type: string
          description: Currency used for fee calculation
        price_per_sol:
          type: string
          nullable: true
          description: Price per SOL at the time of transaction
        signature:
          type: string
          nullable: true
          description: Transaction signature
        created_at:
          type: string
          format: date-time
          description: Timestamp when the record was created
    PaginationInfo:
      type: object
      required:
        - page
        - limit
        - total_count
        - has_next_page
      properties:
        page:
          type: integer
          format: int32
          description: Current page number
        limit:
          type: integer
          format: int32
          description: Number of items per page
        total_count:
          type: integer
          format: int64
          description: Total number of items available
        has_next_page:
          type: boolean
          description: Whether there are more pages available
    Detail:
      type: object
      required:
        - field
        - code
        - message
      properties:
        code:
          type: string
        field:
          type: string
        message:
          type: string
  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.