Connecting Start building
Live#…
Reading the chain…
Network now · GullyChain Testnet
—Live stats
Block
—
Txs · 30 blocks
—
Gas, gwei
—
Launches
—

SDKs: integrate in 5 minutes

On this page

Every Gully product ships a TypeScript SDK on npm under the @gullylabs scope. All of them: ESM and CommonJS builds with types, MIT, semver 0.x, no secrets in the tarball, and a README whose quickstart runs against production in five minutes. Pick the ones you need; each works alone.

Package Use it for Source
@gullylabs/chain Gully Chain itself: chain objects for viem, every address and ABI, launchpad, Gully Swap, .gully names, passkey accounts, bridge, indexer, the gullychain CLI gullychain-sdk (opens in a new tab)
@gullylabs/id Sign in with Gully (OIDC + PKCE), passkey and email sign-in, the account directory gully-id (opens in a new tab)
@gullylabs/pay Gully Pay: x402 micropayments, Agent Wallets, the MCP server, on-chain payment verification gull-pay (opens in a new tab)
@gullylabs/widgets HolderMaps client and <HolderMap> frame, the stock token tracker client and widget sdk (opens in a new tab)
@gullylabs/security Gully Security scans of a token and the "Secured by Gully Security" badge sdk (opens in a new tab)
@gullylabs/kre8-embed kre8.fun coin cards, Drop and track players, "Back this" buttons on your own site sdk (opens in a new tab)
@gullylabs/ads Gully Ads publisher SDK (beta): ad slots with signed serve requests and reporting sdk (opens in a new tab)

Note

Every SDK supports Gully Chain Testnet (chain id 485590) today and will pick up mainnet when it is live. Testnet ETH has no value: see the quickstart for the faucet.

#1. Read and write the chain: @gullylabs/chain

Shell
npm install @gullylabs/chain viem
TypeScript
import { createPublicClient, http, parseEther, formatEther } from 'viem'
import { gullychainTestnet, testnet, launchpad, names, indexer } from '@gullylabs/chain'

const client = createPublicClient({ chain: gullychainTestnet, transport: http() })
console.log(await client.getChainId()) // 485590

const [token] = await launchpad.listTokens(client, { launchpad: testnet.launchpad.deployments[1].address })
const q = await launchpad.quoteBuy(client, token, parseEther('0.01'))
console.log(formatEther(q.tokensOut), 'tokens for 0.01 ETH')

console.log(await names.resolveName(client, 'gully-test'))   // address or null
const { tokens } = await indexer.indexer.tokens()             // no RPC needed

viem is the only dependency (a peer). Subpath imports (@gullylabs/chain/launchpad, /names, /accounts, /abis...) keep bundles small. The gullychain CLI prints addresses and ABIs: npx -p @gullylabs/chain gullychain addresses. Cross-chain buys (one quote across Relay, LI.FI and the Hyperlane warp route, one source-chain transaction) live in @gullylabs/chain/xchain (pickQuote, createXChainBuyClient); see the package's docs/xchain.md.

#2. Sign users in: @gullylabs/id

Shell
npm install @gullylabs/id
TypeScript
import { oidc } from '@gullylabs/id'

const cfg = { issuer: 'https://gullyid.xyz', clientId: 'your-client-id', redirectUri: 'https://yourapp.example/callback' }
const { url, state, verifier } = await oidc.authorizeUrl(cfg)
sessionStorage.setItem('gid', JSON.stringify({ state, verifier }))
location.assign(url)

// on /callback
const q = new URLSearchParams(location.search)
const saved = JSON.parse(sessionStorage.getItem('gid')!)
if (q.get('state') !== saved.state) throw new Error('state mismatch')
const tokens = await oidc.exchangeCode(cfg, q.get('code')!, saved.verifier)

Create the client in the Gully ID console (opens in a new tab). The id_token carries the user's Gully Chain wallet, .gully name and reputation; verify it on your backend with the issuer's JWKS. No build step? The hosted button is at https://gullyid.xyz/sdk/v1.js. More in Gully ID sign-in.

#3. Take payments: @gullylabs/pay

Shell
npm install @gullylabs/pay
TypeScript
import { GullyPayClient, gullyPay } from '@gullylabs/pay'

// An AI agent that pays HTTP 402s from its own wallet, inside its owner's policy
const agent = gullyPay.agent(process.env.GULLYPAY_AGENT_KEY!)
const res = await agent.fetch('https://api.gullypay.xyz/agents/demo/chain-stats')

// Or the x402 facilitator directly
const pay = new GullyPayClient({ facilitatorUrl: 'https://gullypay.xyz/api', apiKey: process.env.GULLYPAY_API_KEY })
console.log(await pay.status()) // networks (Gully Chain included), assets, schemes

@gullylabs/pay/wallet adds on-chain verification (verifyStablecoinPayment), the token registry and wallet helpers (needs viem). Gully Pay is the gateway for every Gully product; docs at gullypay.xyz/docs (opens in a new tab).

#4. Show holders and prices: @gullylabs/widgets

Shell
npm install @gullylabs/widgets
tsx
import { createHoldersClient, isMapOk } from '@gullylabs/widgets/holders'
import { HolderMap } from '@gullylabs/widgets/holders/react'

const map = await createHoldersClient().getMap('gully', '0x9665E20624F3a896067d75e51645e7E73FC35c48')
if (isMapOk(map)) console.log(map.summary.line)

export const Holders = ({ token }: { token: string }) => <HolderMap chain="gully" token={token} height={640} />

The map of any Gully Chain token, who holds it and how the biggest wallets connect, from HolderMaps (opens in a new tab). The same package carries the stock token tracker client and widget.

#5. Prove a token is scanned: @gullylabs/security

Shell
npm install @gullylabs/security
html
<script type="module">
  import { defineSecurityBadge } from '@gullylabs/security'
  defineSecurityBadge()
</script>
<gully-security-badge chain="485590" address="0x..."></gully-security-badge>

The badge is the official "Secured by Gully Security" kit image, linking to the token's public report at gullysecurity.xyz (opens in a new tab). The same package has the typed client to start a scan and read its report.

#6. Embed kre8.fun: @gullylabs/kre8-embed

Shell
npm install @gullylabs/kre8-embed
html
<script type="module">
  import { defineKre8Embeds } from '@gullylabs/kre8-embed'
  defineKre8Embeds()
</script>
<kre8-coin-card coin="0x..."></kre8-coin-card>
<kre8-back-button creator="alice"></kre8-back-button>

Each element is a sandboxed iframe served by kre8.fun; messages are checked against the kre8.fun origin and a per-instance nonce, no auth tokens cross the frame, and any money action opens kre8.fun in a new tab. React: @gullylabs/kre8-embed/react.

#7. Monetise with Gully Ads: @gullylabs/ads (beta)

Shell
npm install @gullylabs/ads@beta
TypeScript
// your server: sign the serve request with your site key; the key never reaches the browser
import { signServeRequest } from '@gullylabs/ads/server'
// your page
import { defineAdSlot } from '@gullylabs/ads'
defineAdSlot()
html
<gully-ad-slot site="your-site-id" slot="sidebar"></gully-ad-slot>

Gully Ads is not live yet (serving is off in production), so the package is published under the beta tag. Impressions count at 50% visible for one second; clicks are reported with the token the server issued with the creative.

#Versions and support

All packages start at 0.x: minor versions may change APIs, patch versions never do. Every repository has a CHANGELOG and a release workflow that publishes with npm provenance. Questions: Community or support.