Query Fee Records

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.

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.

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:

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:

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:

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:

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

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

Performance Optimization

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

Cost Monitoring

Set up alerts: Monitor for unexpected fee spikes
Regular audits: Review fee records periodically
Budget tracking: Compare actual vs expected costs
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

{
  "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

{
  "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

{
  "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.

Authorizations

Authorization

string

header

required

API Key for authentication

Headers

X-Grid-Environment

string

required

The environment you're using. Can be sandbox or production.

Query Parameters

customIdentifier

string

Filter by custom identifier

Response

Successfully retrieved fee records

fees

object[]

required

List of gas abstraction fee records

Show child attributes

fees.id

string<uuid>

required

Unique identifier for the fee record

fees.client_id

string<uuid>

required

Client ID associated with the transaction

fees.custom_identifier

string<uuid>

required

Custom identifier provided during the transaction

fees.currency

string

required

Currency used for fee calculation

fees.created_at

string<date-time>

required

Timestamp when the record was created

fees.confirmation_status

string

Status of the transaction confirmation

fees.tx_fee_lamports

string | null

Transaction fee in lamports

fees.tx_fee_in_currency

string | null

Transaction fee converted to the specified currency

fees.rent_fee_lamports

string | null

Rent fee in lamports

fees.rent_fee_in_currency

string | null

Rent fee converted to the specified currency

fees.price_per_sol

string | null

Price per SOL at the time of transaction

fees.signature

string | null

Transaction signature

pagination

object

required

Pagination information for the response

Show child attributes

pagination.page

integer<int32>

required

Current page number

pagination.limit

integer<int32>

required

Number of items per page

pagination.total_count

integer<int64>

required

Total number of items available

pagination.has_next_page

boolean

required

Whether there are more pages available

Introduction

API Reference

Query Fee Records

Use Cases

Usage Examples

Basic Query

Paginated Retrieval

Date Range Filtering

Cost Analysis

Response Headers

Best Practices

Performance Optimization

Cost Monitoring

Data Retention

Error Handling

Invalid Custom Identifier

Invalid Timestamp Format

Authorizations

Headers

Query Parameters

Response

Introduction

API Reference

​Use Cases

​Usage Examples

​Basic Query

​Paginated Retrieval

​Date Range Filtering

​Cost Analysis

​Pagination Information

​Response Headers

​Best Practices

​Pagination Strategy

​Performance Optimization

​Cost Monitoring

​Data Retention

​Error Handling

​Invalid Custom Identifier

​Invalid Timestamp Format

​Invalid Pagination Parameters

Authorizations

Headers

Query Parameters

Response

Use Cases

Usage Examples

Basic Query

Paginated Retrieval

Date Range Filtering

Cost Analysis

Pagination Information

Response Headers

Best Practices

Pagination Strategy

Performance Optimization

Cost Monitoring

Data Retention

Error Handling

Invalid Custom Identifier

Invalid Timestamp Format

Invalid Pagination Parameters