Bendystraw

Bendystraw is a GraphQL API for the Juicebox protocol built using Ponder, an open-source framework for indexing on-chain events, and maintained by Peri.

Ponder indexes events emitted by the protocol, and stores data in two databases with identical schemas—one for mainnets, and one for testnets. Each has its own URL, and a playground where you can browse the schema and make queries against real data.

Base URL	bendystraw.xyz	testnet.bendystraw.xyz
Chains	Ethereum Arbitrum Base Optimism	Sepolia Arbitrum Sepolia Base Sepolia Optimism Sepolia
Status
	Playground	Playground

Status

Network	Block	Behind
Ethereum	25965695	0 (15s)
Arbitrum One	504601104	58 (16s)
Base	51239627	0 (17s)
OP Mainnet	156834912	0 (17s)
Sepolia	11693159	1 (14s)
Arbitrum Sepolia	308319363	0 (7s)
Base Sepolia	46750161	4 (8s)
OP Sepolia	48733035	? (8s)

Getting Started

Authentication

To make queries, first contact Peri for an API key. API keys should not be exposed. If you need to make requests from a frontend, consider using a server side proxy.

Schema

To download the schema (e.g. for generating graphql types in your frontend):

GET https://bendystraw.xyz/schema (no API key)

Schemas are the same for both mainnet and testnet databases.

GraphQL Queries

POST https://<base-url>/<api-key>/graphql

Singular queries

• Return a single row from a table. Must define primary key for table (e.g. for projects, primary key is compound projectId + chainId + version). Response contains only the row data.

  GraphQL	Response
  project(projectId, chainId, version) { balance volume suckerGroupId ... }	{ project: { balance, volume, suckerGroup, ... } }

Plural queries

• Return multiple rows from a table. Must define at least one of: where, limit, orderBy, orderDirection. Also supports pageInfo and totalCount (see Ponder docs for details).

  GraphQL	Response
  projects( where: { chainId: 1 }, orderBy: "createdAt", orderDirection: "desc", limit: 10 ) { items { balance volume suckerGroupId ... } pageInfo { endCursor hasNextPage ... } totalCount }	{ projects: { totalCount, pageInfo: { endCursor, hasNextPage, ... }, items: { balance, volume, suckerGroupId, ... }[] } }

V6 routing deployments and retained custody

GET /deployments returns this indexer's receipt-backed contract records for its network, including each address, deployment block, package version, artifact path, and generation (current, previous, or v1). current means the canonical deployment artifact; an individual project's registry selection can still point to a previous generation. Historical buyback and router addresses remain indexed after retirement.

Canonical artifact commit a6ab40c5806b52ff4cb21f9eaefe275e621796f9 records executed buyback 1.4.0, router 1.3.0, gateway, and ratio-feed deployments on Ethereum, Arbitrum, Base, Optimism, Sepolia, Base Sepolia, and Arbitrum Sepolia. Optimism Sepolia has the ratio price feed only. The generated records now enable the gateway on all four mainnets at each chain's actual deployment block; existing project pins can still select a retired generation. All V6 activity keeps version: 6, including records from retired V6 contracts.

Gateway custody is available through these GraphQL collections:

Collection	Contents
routerPendingCalls	Original call, memo, metadata, commitment, amount, source/destination project, retry state, and terminal status. Resolved calls stay in history with retainedAmount: 0.
routerPendingCallEvents	Ordered queue, failed retry, settlement, and refund history, including exact emitted failure-class hashes and custody deltas. Sort by block number and log index within a chain.
routerRetainedBalances	Original-token custody grouped by chain, gateway, source project, and token, with cumulative queued, settled, and refunded amounts.
routerPermitFailureEvents	Permit2 failures emitted by current and retired routers. These events have no project ID and do not by themselves imply retained custody.

For example, inspect a source project's custody separately from its recorded terminal balance:

query {
  routerRetainedBalances(where: { chainId: 11155111, sourceProjectId: 2, version: 6 }) {
    items { gateway token retainedAmount pendingCallCount queuedAmount settledAmount refundedAmount }
  }
  routerPendingCalls(where: { chainId: 11155111, sourceProjectId: 2, version: 6 }) {
    items { pendingCallId gateway projectId token amount retainedAmount status latestErrorHash failureCount nextAttemptAt }
  }
}

A queued call retains the original input token. Its first failure is unqualified (failureCount: 0); later qualified failures update the emitted streak and next retry time. A changed error class resets the streak. settled means the retry reached the destination, and refunded means the gateway returned funds through source-project accounting. These amounts are separate from destination revenue and must not be counted as a successful payment while retained. Full revert bytes and retry gas budgets are not emitted by the gateway; use the onchain failure-state read when preparing an executable retry.

After canonical artifacts change, regenerate from the sibling deployment repository and reindex:

npm run generate:rollout -- --ref a6ab40c5806b52ff4cb21f9eaefe275e621796f9
npm run codegen
npm run typecheck
npm test

The generator reads ../deploy-all-v6/deployments (override with --deployments /path/to/deployments). --ref selects a committed artifact snapshot; without it, the current files are read. The example pins the executed production snapshot; choose the newer verified artifact commit for later rollouts, and do not regenerate from an older checkout or branch that predates deployed generations. A successful deployment receipt is required for every included address. Proposed addresses are never indexing sources. The generated ABIs and manifest should be committed together. Changing the schema or restoring older deployment blocks requires the normal Ponder reindex; run TESTNET=true npm run dev against a testnet RPC before production rollout.

Special Queries

Some data is not conveniently accessible via GraphQL, but may be requested via other endpoints.

• /participants Participants snapshot at timestamp

  Retrieve every participantSnapshot object for a sucker group, at a particular timestamp, de-duped by wallet address. Useful for checking all wallets' token balances at a particular point in time.

  Note: Retrieving participants for a particular block height is impractical here, as block numbers are not consistent across chains.

  Request	Response
  POST https://<url>/<api-key>/participants // body { suckerGroupId: "", timestamp: 42069, // unix timestamp (seconds) }	{ chainId, projectId, suckerGroupId, timestamp, block, address, volume, volumeUsd, balance, creditBalance, erc20Balance, }[]

Guides & Patterns

ChainId

Because Bendystraw indexes data from multiple chains, nearly every table includes a chainId property. This is useful for filtering data by chain, or simply differentiating which chain a table row was created from. Nearly every compound primary key also makes use of chainId.

Sucker Groups

A sucker group is a group of linked projects on different chains. These projects act as a single omnichain project, with shared revenue and tokens. While the projects table has a compound primary key of projectId + chainId, the suckerGroups table uses a single id primary key.

Most tables (participants, activityEvents, etc) include a suckerGroupId column, which can be used to filter rows in a graphQL response.

Deterministic unique IDs

project.id and suckerGroup.id are deterministic and will not change. They may be stored or computed to avoid real-time lookups.

• project.id is a string computed from project.projectId, project.version, and project.chainId.
• suckerGroup.id is a hash of the ids of the group's contained projects.

See the Source code for how these ids are computed.

All other unique ids are not deterministic, and may change anytime Bendystraw is reindexed.

Manual events

Two extra manual event tables are indexed for convenience, and have the same schema as their non-manual counterparts:

• manualBurnEvent: Tokens are burned by a project operator, NOT as a result of a cashOut event. burnEvents include ALL token burns.
• manualMintTokensEvent: Tokens are minted by a project operator, NOT as a result of a pay event. mintTokensEvents include ALL token mints.

Links

• Github
• Legal