Mecha Pay GraphQL API Reference

The Mecha Pay subgraph provides a schema-first GraphQL API for querying protocol data on the Arc Testnet. All blockchain events are indexed in real-time and mapped to a structured, relational schema for optimized merchant and subscriber analytics.

Endpoint

Production Endpoint: https://api.studio.thegraph.com/query/1704298/mecha-pay/v0.0.3
Network: Arc Testnet (Chain ID: 5042002)

Schema Overview

The Mecha Pay schema defines two types of entities:

Protocol State Entities: Aggregated, mutable entities representing the current state of plans, sellers, and subscribers.
Event Entities: Immutable records of every historical transaction emitted by the SubscriptionGateway smart contract.

Core Entities

Plan

Represents a subscription plan defined on the smart contract.

Field	Type	Description
`id`	`Bytes!`	Unique plan identifier (bytes32).
`seller`	`Seller!`	The merchant account that created the plan.
`price`	`BigInt!`	Subscription price in USDC (6 fixed decimals).
`duration`	`BigInt!`	Plan validity duration in seconds.
`ipfsHash`	`String!`	IPFS Content Identifier (CID) for plan metadata.
`active`	`Boolean!`	Current operational status of the plan.
`createdAt`	`BigInt!`	Unix timestamp of plan creation.
`updatedAt`	`BigInt!`	Unix timestamp of the most recent update.
`subscriptionCount`	`Int!`	Total number of subscription events for this plan.
`totalGrossVolume`	`BigInt!`	Cumulative revenue generated (USDC).
`totalFeesCollected`	`BigInt!`	Total protocol fees accrued from this plan.
`lastSubscriptionAt`	`BigInt`	Timestamp of the most recent subscription event.

SubscriptionState

Tracks the lifecycle and current status of an individual user's subscription to a specific plan.

Field	Type	Description
`id`	`String!`	Composite ID formatted as `{subscriber_address}-{planId}`.
`subscriber`	`Subscriber!`	The user account holding the subscription.
`seller`	`Seller!`	The merchant providing the subscription.
`plan`	`Plan!`	The associated subscription plan.
`status`	`SubscriptionStatus!`	ENUM: `ACTIVE` or `EXPIRED`.
`subscriptionCount`	`Int!`	Number of times this user has renewed this plan.
`totalSpent`	`BigInt!`	Total USDC spent by this user on this plan.
`lastStartTime`	`BigInt!`	Start timestamp of the current subscription period.
`lastEndTime`	`BigInt!`	Expiry timestamp of the current subscription period.
`lastBuyerData`	`String!`	Most recent metadata provided during subscription.
`updatedAt`	`BigInt!`	Timestamp of the last state transition.

Seller

Aggregated metrics for merchant accounts.

Field	Type	Description
`id`	`Bytes!`	Merchant wallet address.
`planCount`	`Int!`	Total number of plans created by this seller.
`totalGrossRevenue`	`BigInt!`	Total USDC received before protocol fees.
`totalNetRevenue`	`BigInt!`	Total USDC received after protocol fees.
`totalFeeContributed`	`BigInt!`	Total protocol fees generated by this seller.
`subscriptionCount`	`Int!`	Total lifetime subscriptions received.

Event Entities (Historical Logs)

Subscribed

Immutable record of a successful subscription transaction.

Field	Type	Description
`id`	`Bytes!`	Unique event ID.
`subscriber`	`Bytes!`	Address of the subscriber.
`planId`	`Bytes!`	ID of the plan purchased.
`totalAmount`	`BigInt!`	Total USDC paid (6 decimals).
`feeAmount`	`BigInt!`	Protocol fee deducted (6 decimals).
`startTime`	`BigInt!`	Subscription start timestamp.
`endTime`	`BigInt!`	Subscription expiry timestamp.
`transactionHash`	`Bytes!`	Blockchain transaction hash.
`blockTimestamp`	`BigInt!`	Timestamp of the block containing the event.

Querying Logic

Filtering Operators

The API supports standard indexer filtering:

Operator	Description
`_gt` / `_gte`	Greater than / Greater than or equal to.
`_lt` / `_lte`	Less than / Less than or equal to.
`_in` / `_not_in`	Matches / Does not match an array of values.
`_contains`	Substring match (for IPFS hashes or strings).

Pagination and Sorting

All entity collections support:

first: Number of records to return (default 100, max 1000).
skip: Number of records to skip for pagination.
orderBy: Field to sort by.
orderDirection: asc or desc.

Metadata Standard

Mecha Pay uses IPFS to store plan metadata (service name, branding, and feature list). The ipfsHash field in the Plan entity refers to a JSON object with the following schema:

json
{
  "type": "subscription-ui",
  "version": "1.0",
  "name": "Service Name",
  "brand": {
    "name": "Brand Name",
    "website": "https://brand.com"
  },
  "features": [
    {
      "title": "Feature Title",
      "description": "Feature Details"
    }
  ]
}

Validation Rules

type: Must be strictly set to "subscription-ui".
version: Must be strictly set to "1.0".
brand: Requires both name and website.
features: Must be a non-empty array of objects with title and description.

GraphQL API Reference

Real-time Indexing

Flexible Queries

Aggregated Stats

Decentralized