npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

fareql

v0.2.0

Published

Charge for GraphQL operations over MPP (HTTP 402), priced by what each operation selects, with optional identity tiers that charge verified callers less. Plugins for GraphQL Yoga and Apollo Server, plus a wrapper for any Fetch handler.

Readme

Try it in the browser at fareql.pages.dev. Type a query and the meter quotes it live. Pay with a demo method and you get the data and a receipt. No money moves. Shortcuts: pay for a search · slide a page size · try to ride for free

Verified on Tempo mainnet: a real tempo.charge payment of 0.001 USDC.e through FareQL, settled on chain: 0xc1f2a9f1…28bd (testnet: 0x4fcba990…d346).

Why FareQL

A GraphQL API is one endpoint, so a flat price per route doesn't fit it: { hello } and { users(first: 100) { edges { node { email } } } } hit the same URL. FareQL works out the fare of every operation from your schema and charges it through mppx with Tempo, Stripe or any other MPP method. Clients (apps, scripts, AI agents) pay per question. They don't need an account, an API key or a plan, and the money goes straight to your address.

| | | |---|---| | Schema-driven prices | @price(amount: "0.001") on fields and types, multiplied through lists, Relay connections and @listSize | | One Challenge per operation | Bound to the exact document and variables. A Credential for a cheap query can't pay for an expensive one | | Charged after validation | Persisted queries and depth limits run first, so nobody pays for an operation the server refuses | | Fails closed | If FareQL can't read or price an operation, the operation doesn't run | | Red-teamed | About 100 attack tests: parser differentials, cache bypasses, fragment bombs, scope collisions | | Works where you are | GraphQL Yoga, Apollo Server 4/5 and any Fetch handler (Hono, Next.js, Workers), on graphql 16 and 17 |

Quick start

npm install fareql mppx graphql
import { createSchema, createYoga } from 'graphql-yoga'
import { Mppx, tempo } from 'mppx/server'
import { fareDirectiveTypeDefs } from 'fareql'
import { useFareql } from 'fareql/yoga'

const mppx = Mppx.create({
  methods: [tempo.charge({ currency: '0x…' /* TIP-20 token */, recipient: '0x…' })],
})

const yoga = createYoga({
  schema: createSchema({
    typeDefs: /* GraphQL */ `
      ${fareDirectiveTypeDefs}
      type Query {
        hello: String
        weather(city: String!): Forecast @price(amount: "0.001")
        search(query: String!, first: Int = 5): [Hit!]! @price(amount: "0.0005")
      }
      type Forecast { temperature: Float }
      type Hit { title: String, snippet: String @price(amount: "0.0002") }
    `,
    resolvers,
  }),
  plugins: [useFareql({ charge: (o) => mppx.charge(o), pricing: { maxPrice: '1' } })],
})

{ hello } is free. { search(query: "mpp", first: 2) { snippet } } costs 2 × (0.0005 + 0.0002) = 0.0014.

How it works

  1. You price your schema. Put @price(amount: "0.001") on whatever costs money.
  2. A client asks. FareQL prices the operation from what it selects. Free operations run as usual.
  3. It gets a quote. A priced operation answers 402 Payment Required with an MPP Challenge for that exact operation, plus the price and its breakdown.
  4. It pays and asks again. The client (an app, the mppx CLI, an AI agent) pays, for example in stablecoins on Tempo, and resends the query with the Credential.
  5. It gets the answer. FareQL verifies the Credential through mppx, runs the operation and returns the data with a Payment-Receipt.

Use it with your server

GraphQL Yoga

Shown in Quick start. Register useFareql after plugins that change what runs (APQ, persisted operations, validation rules). It hooks into execution, so it always prices the final document. A backstop before each response charges results that never reached execution, so a response cache or a plugin that short-circuits can't serve a priced result for free.

Yoga-only options:

  • getRequest(context) supplies the HTTP request for transports that have none, such as graphql-ws. Without it, priced operations over those transports are refused.
  • maxSubscriptionEvents (default 100) is how many events one payment buys on a priced subscription.

Apollo Server

import { ApolloServer } from '@apollo/server'
import { fareqlApolloPlugin } from 'fareql/apollo'

const server = new ApolloServer({
  typeDefs,
  resolvers,
  plugins: [fareqlApolloPlugin({ charge: (o) => mppx.charge(o) })],
})

The plugin charges in didResolveOperation. By then Apollo has parsed, validated and resolved the operation (APQ included), and its response cache hasn't answered yet. In an HTTP batch only one priced operation can be paid. Operations run in-process with server.executeOperation() have no HTTP request and are not charged.

Any Fetch handler (Hono, Next.js, graphql-http, Cloudflare Workers)

import { withPayment } from 'fareql'

export const POST = withPayment((req) => handler(req), { schema, charge: (o) => mppx.charge(o) })

withPayment reads the request itself, so it refuses anything the wrapped handler could read differently:

  • Content types are matched exactly and case-sensitively, as GraphQL Yoga does, so the gate never accepts a body the handler would refuse.
  • It accepts GET and application/json POST by default. Enable application/graphql, application/graphql+json, form-urlencoded or multipart uploads with encodings: [...], but only if your handler accepts them too.
  • It refuses the following with a 4xx before anything is charged:
    • URL fragments, duplicate or unknown parameters, and GraphQL parameters in a POST URL;
    • non-object variables, and query sent together with documentId;
    • bodies on other methods, and mutations over GET.
  • maxBodyBytes (1 MB), maxQueryLength (100 000), maxTokens (15 000) and maxBatchSize (10) bound the work.
  • validationRules adds your server's extra rules, so operations they would reject are refused before payment.
  • APQ works without a hash store in the gate: a hash-only request gets PersistedQueryNotFound and the full query the client resends is priced, so nobody pays for a hash the handler doesn't know. To price hashes or trusted documents (documentId) from your own store, pass resolveDocument.
  • Batches are refused unless you set batching: true. With it, the whole batch is charged in one payment and maxPrice applies to the total.

For full control, createPaymentGate(options)(request) returns one of free, payment-required, paid or rejected.

Mainnet or testnet

FareQL doesn't pick a network. It prices the operation and hands the amount to mppx, and your mppx configuration decides where it is paid.

// Tempo mainnet: USDC.e
tempo.charge({ currency: '0x20C000000000000000000000b9537d11c60E8b50', recipient: '0x…' })

// Moderato testnet: pathUSD
tempo.charge({ currency: '0x20c0000000000000000000000000000000000001', recipient: '0x…', testnet: true })
  • The examples and the playground run on mainnet by default. Set TEMPO_NETWORK=testnet to use Moderato.
  • Clients read the network from the Challenge's chainId.
    • The mppx CLI uses mainnet by default. Add --network testnet to pay a testnet API.
    • Testnet funds come from npx mppx account fund.

Pricing rules

| Rule | Behaviour | |---|---| | Field @price | Charged once per resolved instance of the field | | Type @price | Applies to every field returning that type, unless the field has its own | | Field selected several times | Charged once per response key, as the executor resolves it | | Lists | Children × list size from first, last, limit, take, top, pageSize or perPage (also inside an input object, e.g. page: { limit }), otherwise defaultListSize (10). Capped at maxListSize (100). null or unbounded counts as maxListSize; negative sizes are refused | | Nested lists | [[Cell]]: each inner level multiplies by defaultListSize | | Connections and page wrappers | A non-list field given a size (users(first: 50)) passes it to the lists it selects (edges, nodes, items…). Restrict with connections: { sizedFields }, or turn it off with false | | @listSize | As in the IBM GraphQL Cost Directives draft: slicingArguments, sizedFields, assumedSize, requireOneSlicingArgument | | Interfaces and unions | Every possible runtime type is priced and the most expensive one is charged. A @price on an interface field or type applies to its implementations | | Code-first schemas | extensions: { price: '0.001' } or extensions: { directives: { price: { amount: '0.001' } } } | | Fragments, @skip, @include | Followed and evaluated with the request variables | | __typename, introspection | Free | | maxPrice | Operations above it get PRICE_LIMIT_EXCEEDED before any Challenge | | maxFieldVisits, maxDepth | Operations too complex to price get TOO_COMPLEX (10 000 selections, 100 levels) | | No price anywhere | A schema with no @price at all (e.g. one that lost its directives) is refused with NO_PRICES instead of making everything free |

Other options:

  • decimals (default 6) must match your payment method's token.
  • defaultFieldPrice, listSizeArguments, connections.
  • fieldPrice(ctx) prices fields in code.

priceOperation() is exported for quotes and tests.

Identity tiers

Charge callers less the more they prove about themselves. Any request-stage mppx/identity verifier works (Identity.from over your API keys, EmailOtp.Server.verifier, WebBotAuth.Server.verifier, Identity.anyOf(...)), or your own object with a verify(request) method.

useFareql({
  charge: (o) => mppx.charge(o),
  tiers: [ // best first: the first verifier that accepts the request sets the price
    { name: 'member', verifier: apiKeys, multiplier: '0.25' },
    { name: 'verified', verifier: email, multiplier: '0.5' },
  ],
  // anonymous: false, // require a proof for priced operations
})
  • Callers without a proof pay the base price. multiplier: '0' makes priced operations free for that tier. Tier prices round up to the smallest unit.
  • A proof that is presented but refused is answered with its own status (401, 403, or 503 when the issuer is down) and is never charged at a dearer tier.
  • Each verifier runs once per request. The tier is bound into the Challenge scope, so a Credential bought at a tier's price is refused when the retry drops that tier's proof.
  • maxPrice applies to the base price, so every tier has the same complexity limit.
  • 402 bodies add tier, baseAmount and the price in each tier (tiers) unless exposePrice is false.

What clients get

HTTP/1.1 402 Payment Required
WWW-Authenticate: Payment id="…", realm="api.example.com", method="tempo", intent="charge", request="…"
Content-Type: application/json; charset=utf-8

{
  "errors": [{
    "message": "Payment required: this operation costs 0.0014",
    "extensions": {
      "code": "PAYMENT_REQUIRED",
      "price": {
        "amount": "0.0014",
        "breakdown": [
          { "path": "search", "unitAmount": "0.0005", "count": "2", "amount": "0.001" },
          { "path": "search.snippet", "unitAmount": "0.0002", "count": "2", "amount": "0.0004" }
        ]
      }
    }
  }]
}

Clients need nothing from FareQL, only an MPP client. With the mppx CLI, an account and a little USDC.e on Tempo:

npx mppx account create        # then send the account a little USDC.e
npx mppx https://api.example.com/graphql -X POST -H 'content-type: application/json' \
  -d '{"query":"{ search(query: \"mpp\", first: 2) { snippet } }"}'

For an API on the Moderato testnet, fund the account with npx mppx account fund and add --network testnet.

In code, mppx/client wraps fetch, so 402s are paid and retried automatically. The paid response carries a Payment-Receipt and Cache-Control: private, so shared caches never store paid content. Set exposePrice: false to keep prices out of error bodies.

Security model

  • Binding. Each Challenge's scope is a hash of the printed document, the operation name and the declared variables. mppx keeps it in the HMAC-protected Challenge and refuses a Credential whose scope differs.
  • Price what runs. Yoga and Apollo charge after the server's own parsing, validation and persisted-document lookup. withPayment refuses requests a handler could parse differently.
  • Fail closed. Unreadable, unpriceable, over-limit or ambiguous requests are answered with an error and never run.
  • Bounded work. Pricing is linear in the document, like graphql-js field collection. Token, length, depth, body and batch limits keep it cheap.
  • Tested by attack. test/attacks-*.test.ts hold the red-team suites. Each test asserts the secure behaviour.

Reference

| Option | | |---|---| | charge | (o) => mppx.charge(o), or (o) => mppx.tempo.charge(o) when several methods are configured. Receives { amount, scope, description } | | pricing | See Pricing rules | | describe(op, price) | Challenge description. Default: GraphQL <operation name> | | exposePrice | Include the price breakdown in 402 bodies. Default: true | | tiers, anonymous | See Identity tiers |

  • Payment settles before execution, so a resolver error after payment is not refunded. Keep priced resolvers reliable.
  • Subscriptions are charged once, when they start, for up to maxSubscriptionEvents events. Metered streams over MPP sessions are planned.
  • Set maxListSize to your server's real page cap. If the server returns more items than maxListSize, the client is under-charged, because larger requested sizes are clamped.
  • In production, give tempo.charge() a shared store so a Credential can't be replayed across instances.

Examples

  • examples/playground: the live demo. Run it locally with npx tsx examples/playground/server.ts. Set RECIPIENT and MPP_SECRET_KEY for real payments on Tempo mainnet, plus TEMPO_NETWORK=testnet for the Moderato testnet.
  • examples/yoga-tempo: a minimal GraphQL Yoga server on Tempo (mainnet by default, TEMPO_NETWORK=testnet for Moderato).
  • examples/apollo-tempo: Apollo Server with a priced Relay-style connection.

Development

npm test                                  # pricing, gate, Yoga, Apollo, attacks, real mppx loops
npm run build && node scripts/smoke.mjs   # the built package over real HTTP in plain Node

License

MIT