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. Include your Grid API key in the Authorization header.

Headers

X-Grid-Environment

enum<string>

required

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

Available options:

sandbox,

production

Query Parameters

customIdentifier

string<uuid>

Filter fee records by custom identifier

startDate

string<date-time>

Filter records from this timestamp (ISO 8601 format)

endDate

string<date-time>

Filter records until this timestamp (ISO 8601 format)

page

integer

default:1

Page number for pagination

Required range: x >= 1

limit

integer

default:50

Number of records per page

Required range: 1 <= x <= 1000

Response

Successfully retrieved fee records

data

object

required

Show child attributes

requestId

string

required

Unique identifier for this API request

Example:

"req_550e8400e29b41d4a716446655440000"

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