data

package
v0.0.0-...-32810c0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jan 22, 2026 License: MIT Imports: 14 Imported by: 0

Documentation

Overview

Package data provides the Data API client for Alchemy's enhanced APIs.

Index

Constants

View Source
const WebhookSignatureHeader = "X-Alchemy-Signature"

WebhookSignatureHeader is the HTTP header containing the webhook signature.

Variables

This section is empty.

Functions

func VerifyWebhookSignature

func VerifyWebhookSignature(signingKey, signature string, payload []byte) bool

VerifyWebhookSignature verifies the signature of a webhook payload. signingKey is the webhook's signing key from the dashboard. signature is the value of the X-Alchemy-Signature header. payload is the raw request body.

Types

type AcquiredAt

type AcquiredAt struct {
	// BlockTimestamp is when the NFT was acquired.
	BlockTimestamp *string `json:"blockTimestamp,omitempty"`
	// BlockNumber is the block number.
	BlockNumber *string `json:"blockNumber,omitempty"`
}

AcquiredAt contains NFT acquisition information.

type ActivityLog

type ActivityLog struct {
	// Address is the contract address.
	Address string `json:"address"`
	// Topics is the list of log topics.
	Topics []string `json:"topics"`
	// Data is the log data.
	Data string `json:"data"`
	// BlockNumber is the block number (hex).
	BlockNumber string `json:"blockNumber"`
	// TransactionHash is the transaction hash.
	TransactionHash string `json:"transactionHash"`
	// TransactionIndex is the transaction index (hex).
	TransactionIndex string `json:"transactionIndex"`
	// BlockHash is the block hash.
	BlockHash string `json:"blockHash"`
	// LogIndex is the log index (hex).
	LogIndex string `json:"logIndex"`
	// Removed indicates if the log was removed.
	Removed bool `json:"removed"`
}

ActivityLog contains log information for token transfers.

type AddressActivity

type AddressActivity struct {
	// FromAddress is the sender address.
	FromAddress string `json:"fromAddress"`
	// ToAddress is the recipient address.
	ToAddress string `json:"toAddress"`
	// BlockNum is the block number (hex).
	BlockNum string `json:"blockNum"`
	// Hash is the transaction hash.
	Hash string `json:"hash"`
	// Value is the value transferred.
	Value float64 `json:"value"`
	// Asset is the asset symbol.
	Asset string `json:"asset"`
	// Category is the transfer category.
	Category string `json:"category"`
	// RawContract contains raw contract info.
	RawContract *RawContractInfo `json:"rawContract,omitempty"`
	// Log contains log info (for token transfers).
	Log *ActivityLog `json:"log,omitempty"`
}

AddressActivity represents a single address activity.

type AddressActivityEvent

type AddressActivityEvent struct {
	// Network is the blockchain network.
	Network string `json:"network"`
	// Activity contains the activity details.
	Activity []AddressActivity `json:"activity"`
}

AddressActivityEvent represents an address activity event.

func ParseAddressActivityEvent

func ParseAddressActivityEvent(event *WebhookEvent) (*AddressActivityEvent, error)

ParseAddressActivityEvent parses the event data as an AddressActivityEvent.

type AssetTransfer

type AssetTransfer struct {
	// Category is the type of transfer.
	Category AssetTransferCategory `json:"category"`
	// BlockNum is the block number (hex).
	BlockNum string `json:"blockNum"`
	// From is the sender address.
	From types.Address `json:"from"`
	// To is the recipient address.
	To *types.Address `json:"to,omitempty"`
	// Value is the transferred value (as decimal number).
	Value *float64 `json:"value,omitempty"`
	// TokenID is the NFT token ID.
	TokenID *string `json:"tokenId,omitempty"`
	// ERC1155Metadata contains ERC1155 token metadata.
	ERC1155Metadata []ERC1155Metadata `json:"erc1155Metadata,omitempty"`
	// Asset is the asset symbol (e.g., "ETH", "USDC").
	Asset *string `json:"asset,omitempty"`
	// UniqueID is the unique identifier for this transfer.
	UniqueID string `json:"uniqueId"`
	// Hash is the transaction hash.
	Hash types.Hash `json:"hash"`
	// RawContract contains raw contract information.
	RawContract RawContract `json:"rawContract"`
	// Metadata contains additional metadata (when WithMetadata is true).
	Metadata *TransferMetadata `json:"metadata,omitempty"`
}

AssetTransfer represents a single asset transfer.

func (*AssetTransfer) BlockNumber

func (t *AssetTransfer) BlockNumber() uint64

BlockNumber returns the block number as uint64.

type AssetTransferCategory

type AssetTransferCategory string

AssetTransferCategory represents the type of asset transfer.

const (
	CategoryExternal   AssetTransferCategory = "external"
	CategoryInternal   AssetTransferCategory = "internal"
	CategoryERC20      AssetTransferCategory = "erc20"
	CategoryERC721     AssetTransferCategory = "erc721"
	CategoryERC1155    AssetTransferCategory = "erc1155"
	CategorySpecialNFT AssetTransferCategory = "specialnft"
)

Asset transfer categories.

type AssetTransfersIterator

type AssetTransfersIterator struct {
	// contains filtered or unexported fields
}

AssetTransfersIterator iterates through asset transfers with pagination.

func (*AssetTransfersIterator) Collect

func (it *AssetTransfersIterator) Collect() ([]AssetTransfer, error)

Collect returns all remaining transfers as a slice. Use with caution on large result sets.

func (*AssetTransfersIterator) CollectN

func (it *AssetTransfersIterator) CollectN(n int) ([]AssetTransfer, error)

CollectN returns up to n transfers.

func (*AssetTransfersIterator) Error

func (it *AssetTransfersIterator) Error() error

Error returns any error encountered during iteration.

func (*AssetTransfersIterator) HasNext

func (it *AssetTransfersIterator) HasNext() bool

HasNext returns true if there are more transfers to iterate.

func (*AssetTransfersIterator) Next

Next returns the next transfer in the iteration. Returns nil when there are no more transfers.

func (*AssetTransfersIterator) Reset

func (it *AssetTransfersIterator) Reset()

Reset resets the iterator to the beginning.

type AssetTransfersParams

type AssetTransfersParams struct {
	// FromBlock is the starting block (hex or "latest").
	FromBlock string `json:"fromBlock,omitempty"`
	// ToBlock is the ending block (hex or "latest").
	ToBlock string `json:"toBlock,omitempty"`
	// FromAddress filters transfers from this address.
	FromAddress *types.Address `json:"fromAddress,omitempty"`
	// ToAddress filters transfers to this address.
	ToAddress *types.Address `json:"toAddress,omitempty"`
	// ContractAddresses filters transfers by contract addresses.
	ContractAddresses []types.Address `json:"contractAddresses,omitempty"`
	// Category is the list of transfer categories to include.
	Category []AssetTransferCategory `json:"category"`
	// Order is the sort order (asc or desc).
	Order SortOrder `json:"order,omitempty"`
	// WithMetadata includes block timestamps in the response.
	WithMetadata bool `json:"withMetadata,omitempty"`
	// ExcludeZeroValue excludes zero-value transfers.
	ExcludeZeroValue bool `json:"excludeZeroValue,omitempty"`
	// MaxCount is the maximum number of results per page (hex).
	MaxCount string `json:"maxCount,omitempty"`
	// PageKey is the pagination key for fetching more results.
	PageKey string `json:"pageKey,omitempty"`
}

AssetTransfersParams represents the parameters for getAssetTransfers.

func NewAssetTransfersParams

func NewAssetTransfersParams() *AssetTransfersParams

NewAssetTransfersParams creates a new AssetTransfersParams with default values.

func (*AssetTransfersParams) SetCategories

func (p *AssetTransfersParams) SetCategories(categories []AssetTransferCategory) *AssetTransfersParams

SetCategories sets the transfer categories.

func (*AssetTransfersParams) SetContractAddresses

func (p *AssetTransfersParams) SetContractAddresses(addresses []types.Address) *AssetTransfersParams

SetContractAddresses sets the contract address filter.

func (*AssetTransfersParams) SetFromAddress

func (p *AssetTransfersParams) SetFromAddress(address types.Address) *AssetTransfersParams

SetFromAddress sets the from address filter.

func (*AssetTransfersParams) SetFromBlock

func (p *AssetTransfersParams) SetFromBlock(block string) *AssetTransfersParams

SetFromBlock sets the starting block.

func (*AssetTransfersParams) SetMaxCount

func (p *AssetTransfersParams) SetMaxCount(count int) *AssetTransfersParams

SetMaxCount sets the maximum number of results.

func (*AssetTransfersParams) SetOrder

SetOrder sets the sort order.

func (*AssetTransfersParams) SetToAddress

func (p *AssetTransfersParams) SetToAddress(address types.Address) *AssetTransfersParams

SetToAddress sets the to address filter.

func (*AssetTransfersParams) SetToBlock

func (p *AssetTransfersParams) SetToBlock(block string) *AssetTransfersParams

SetToBlock sets the ending block.

func (*AssetTransfersParams) SetWithMetadata

func (p *AssetTransfersParams) SetWithMetadata(withMetadata bool) *AssetTransfersParams

SetWithMetadata enables metadata in the response.

type AssetTransfersResponse

type AssetTransfersResponse struct {
	// PageKey is the pagination key for fetching more results.
	PageKey string `json:"pageKey,omitempty"`
	// Transfers is the list of asset transfers.
	Transfers []AssetTransfer `json:"transfers"`
}

AssetTransfersResponse represents the response from getAssetTransfers.

func (*AssetTransfersResponse) HasMore

func (r *AssetTransfersResponse) HasMore() bool

HasMore returns true if there are more results available.

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client is the Data API client.

func NewClient

func NewClient(httpClient *client.HTTPClient, rpc *client.JSONRPCClient, nftURL string) *Client

NewClient creates a new Data API client.

func (*Client) GetAssetTransfers

func (c *Client) GetAssetTransfers(ctx context.Context, params *AssetTransfersParams) (*AssetTransfersResponse, error)

GetAssetTransfers retrieves asset transfers matching the given parameters.

func (*Client) GetAssetTransfersEnhanced

func (c *Client) GetAssetTransfersEnhanced(ctx context.Context, params *AssetTransfersParams) (*AssetTransfersResponse, error)

GetAssetTransfersEnhanced retrieves all asset transfers by automatically handling pagination. It continues fetching pages until no more results are available (pageKey is empty).

func (*Client) GetAssetTransfersIterator

func (c *Client) GetAssetTransfersIterator(ctx context.Context, params *AssetTransfersParams) *AssetTransfersIterator

GetAssetTransfersIterator returns an iterator for paginating through asset transfers.

func (*Client) GetContractMetadata

func (c *Client) GetContractMetadata(ctx context.Context, contractAddress types.Address) (*NFTContractMetadata, error)

GetContractMetadata retrieves metadata for an NFT contract.

func (*Client) GetNFTMetadata

func (c *Client) GetNFTMetadata(ctx context.Context, params *NFTMetadataParams) (*OwnedNFT, error)

GetNFTMetadata retrieves metadata for a specific NFT.

func (*Client) GetNFTsForContract

func (c *Client) GetNFTsForContract(ctx context.Context, contractAddress types.Address, pageKey string, withMetadata bool) (*NFTsForContractResponse, error)

GetNFTsForContract retrieves all NFTs for a contract.

func (*Client) GetNFTsForOwner

func (c *Client) GetNFTsForOwner(ctx context.Context, params *NFTsForOwnerParams) (*NFTsForOwnerResponse, error)

GetNFTsForOwner retrieves NFTs owned by an address.

func (*Client) GetNFTsForOwnerIterator

func (c *Client) GetNFTsForOwnerIterator(ctx context.Context, params *NFTsForOwnerParams) *NFTsForOwnerIterator

GetNFTsForOwnerIterator returns an iterator for paginating through NFTs.

func (*Client) GetOwnersForContract

func (c *Client) GetOwnersForContract(ctx context.Context, contractAddress types.Address, pageKey string, withTokenBalances bool) (*OwnersForContractResponse, error)

GetOwnersForContract retrieves all owners for an NFT contract.

func (*Client) GetOwnersForNFT

func (c *Client) GetOwnersForNFT(ctx context.Context, contractAddress types.Address, tokenID string) (*OwnersForNFTResponse, error)

GetOwnersForNFT retrieves owners for a specific NFT.

func (*Client) GetTokenAllowance

func (c *Client) GetTokenAllowance(ctx context.Context, params *TokenAllowanceParams) (*TokenAllowanceResponse, error)

GetTokenAllowance retrieves the allowance for a spender.

func (*Client) GetTokenBalances

func (c *Client) GetTokenBalances(ctx context.Context, params *TokenBalancesParams) (*TokenBalancesResponse, error)

GetTokenBalances retrieves token balances for an address.

func (*Client) GetTokenBalancesForAddresses

func (c *Client) GetTokenBalancesForAddresses(ctx context.Context, addresses []types.Address, contractAddresses []types.Address) (map[types.Address]*TokenBalancesResponse, error)

GetTokenBalancesForAddresses retrieves token balances for multiple addresses. This is a convenience method that makes multiple calls.

func (*Client) GetTokenMetadata

func (c *Client) GetTokenMetadata(ctx context.Context, contractAddress types.Address) (*TokenMetadata, error)

GetTokenMetadata retrieves metadata for a token.

func (*Client) GetTokensForOwner

func (c *Client) GetTokensForOwner(ctx context.Context, owner types.Address, pageKey string) (*TokensForOwnerResponse, error)

GetTokensForOwner retrieves all tokens owned by an address.

func (*Client) HTTP

func (c *Client) HTTP() *client.HTTPClient

HTTP returns the underlying HTTP client.

func (*Client) IsSpamContract

func (c *Client) IsSpamContract(ctx context.Context, contractAddress types.Address) (bool, error)

IsSpamContract checks if a contract is classified as spam.

func (*Client) RPC

func (c *Client) RPC() *client.JSONRPCClient

RPC returns the underlying JSON-RPC client.

type ContractOwner

type ContractOwner struct {
	// OwnerAddress is the owner's address.
	OwnerAddress types.Address `json:"ownerAddress"`
	// TokenBalances contains the tokens owned (if withTokenBalances is true).
	TokenBalances []TokenBalanceEntry `json:"tokenBalances,omitempty"`
}

ContractOwner represents an owner of NFTs in a contract.

type CreateWebhookParams

type CreateWebhookParams struct {
	// Network is the blockchain network.
	Network WebhookNetwork `json:"network"`
	// WebhookType is the type of webhook to create.
	WebhookType WebhookType `json:"webhook_type"`
	// WebhookURL is the URL where webhook events will be sent.
	WebhookURL string `json:"webhook_url"`
	// Addresses is the list of addresses to track (for ADDRESS_ACTIVITY webhooks).
	Addresses []string `json:"addresses,omitempty"`
	// NFTFilters is the list of NFT filters (for NFT_ACTIVITY webhooks).
	NFTFilters []NFTWebhookFilter `json:"nft_filters,omitempty"`
	// GraphQLQuery is the GraphQL query (for GRAPHQL webhooks).
	GraphQLQuery *string `json:"graphql_query,omitempty"`
	// AppID is the app ID to associate with the webhook (optional).
	AppID *string `json:"app_id,omitempty"`
}

CreateWebhookParams represents the parameters for creating a webhook.

func NewAddressActivityWebhookParams

func NewAddressActivityWebhookParams(network WebhookNetwork, webhookURL string, addresses []string) *CreateWebhookParams

NewAddressActivityWebhookParams creates parameters for an ADDRESS_ACTIVITY webhook.

func NewGraphQLWebhookParams

func NewGraphQLWebhookParams(network WebhookNetwork, webhookURL string, query string) *CreateWebhookParams

NewGraphQLWebhookParams creates parameters for a GRAPHQL (custom) webhook.

func NewNFTActivityWebhookParams

func NewNFTActivityWebhookParams(network WebhookNetwork, webhookURL string, filters []NFTWebhookFilter) *CreateWebhookParams

NewNFTActivityWebhookParams creates parameters for an NFT_ACTIVITY webhook.

type CreateWebhookResponse

type CreateWebhookResponse struct {
	// Data contains the created webhook.
	Data Webhook `json:"data"`
}

CreateWebhookResponse represents the response from creating a webhook.

type ERC1155Metadata

type ERC1155Metadata struct {
	// TokenID is the token ID (hex).
	TokenID string `json:"tokenId"`
	// Value is the amount transferred (hex).
	Value string `json:"value"`
}

ERC1155Metadata contains ERC1155 token metadata.

type GetWebhookAddressesParams

type GetWebhookAddressesParams struct {
	// WebhookID is the ID of the webhook.
	WebhookID string `json:"webhook_id"`
	// Limit is the maximum number of addresses to return per page.
	Limit int `json:"limit,omitempty"`
	// After is the cursor for pagination.
	After string `json:"after,omitempty"`
	// PageKey is the page key for pagination.
	PageKey string `json:"pageKey,omitempty"`
}

GetWebhookAddressesParams represents the parameters for getting webhook addresses.

type GetWebhookAddressesResponse

type GetWebhookAddressesResponse struct {
	// Data contains the list of addresses.
	Data []string `json:"data"`
	// Pagination contains pagination information.
	Pagination WebhookPagination `json:"pagination"`
}

GetWebhookAddressesResponse represents the response from getting webhook addresses.

func (*GetWebhookAddressesResponse) HasMore

func (r *GetWebhookAddressesResponse) HasMore() bool

HasMore returns true if there are more addresses to fetch.

type GetWebhooksResponse

type GetWebhooksResponse struct {
	// Data contains the list of webhooks.
	Data []Webhook `json:"data"`
}

GetWebhooksResponse represents the response from the team-webhooks endpoint.

type NFTAttribute

type NFTAttribute struct {
	// TraitType is the trait type.
	TraitType *string `json:"trait_type,omitempty"`
	// Value is the trait value.
	Value interface{} `json:"value,omitempty"`
	// DisplayType is the display type.
	DisplayType *string `json:"display_type,omitempty"`
}

NFTAttribute represents an NFT attribute.

type NFTCollection

type NFTCollection struct {
	// Name is the collection name.
	Name *string `json:"name,omitempty"`
	// Slug is the collection slug.
	Slug *string `json:"slug,omitempty"`
	// ExternalURL is the external URL.
	ExternalURL *string `json:"externalUrl,omitempty"`
	// BannerImageURL is the banner image URL.
	BannerImageURL *string `json:"bannerImageUrl,omitempty"`
}

NFTCollection contains collection information.

type NFTContract

type NFTContract struct {
	// Address is the contract address.
	Address types.Address `json:"address"`
	// Name is the contract name.
	Name *string `json:"name,omitempty"`
	// Symbol is the contract symbol.
	Symbol *string `json:"symbol,omitempty"`
	// TotalSupply is the total supply.
	TotalSupply *string `json:"totalSupply,omitempty"`
	// TokenType is the token type.
	TokenType string `json:"tokenType"`
	// ContractDeployer is the deployer address.
	ContractDeployer *string `json:"contractDeployer,omitempty"`
	// DeployedBlockNumber is the deployment block number.
	DeployedBlockNumber *int64 `json:"deployedBlockNumber,omitempty"`
	// OpenSeaMetadata contains OpenSea metadata.
	OpenSeaMetadata *OpenSeaMetadata `json:"openseaMetadata,omitempty"`
	// IsSpam indicates if the contract is marked as spam.
	IsSpam *bool `json:"isSpam,omitempty"`
	// SpamClassifications contains spam classification reasons.
	SpamClassifications []string `json:"spamClassifications,omitempty"`
}

NFTContract represents NFT contract information.

type NFTContractMetadata

type NFTContractMetadata struct {
	// Address is the contract address.
	Address types.Address `json:"address"`
	// Name is the contract name.
	Name *string `json:"name,omitempty"`
	// Symbol is the contract symbol.
	Symbol *string `json:"symbol,omitempty"`
	// TotalSupply is the total supply.
	TotalSupply *string `json:"totalSupply,omitempty"`
	// TokenType is the token type.
	TokenType string `json:"tokenType"`
	// ContractDeployer is the deployer address.
	ContractDeployer *string `json:"contractDeployer,omitempty"`
	// DeployedBlockNumber is the deployment block number.
	DeployedBlockNumber *int64 `json:"deployedBlockNumber,omitempty"`
	// OpenSeaMetadata contains OpenSea metadata.
	OpenSeaMetadata *OpenSeaMetadata `json:"openseaMetadata,omitempty"`
}

NFTContractMetadata represents contract-level NFT metadata.

type NFTFilter

type NFTFilter string

NFTFilter represents a filter for NFT queries.

const (
	NFTFilterSpam     NFTFilter = "SPAM"
	NFTFilterAirdrops NFTFilter = "AIRDROPS"
)

NFT filters.

type NFTImage

type NFTImage struct {
	// CachedURL is the cached image URL.
	CachedURL *string `json:"cachedUrl,omitempty"`
	// ThumbnailURL is the thumbnail URL.
	ThumbnailURL *string `json:"thumbnailUrl,omitempty"`
	// PngURL is the PNG URL.
	PngURL *string `json:"pngUrl,omitempty"`
	// ContentType is the content type.
	ContentType *string `json:"contentType,omitempty"`
	// Size is the image size in bytes.
	Size *int `json:"size,omitempty"`
	// OriginalURL is the original image URL.
	OriginalURL *string `json:"originalUrl,omitempty"`
}

NFTImage contains NFT image information.

type NFTMetadataParams

type NFTMetadataParams struct {
	// ContractAddress is the NFT contract address.
	ContractAddress types.Address `json:"contractAddress"`
	// TokenID is the token ID.
	TokenID string `json:"tokenId"`
	// TokenType is the token type (optional).
	TokenType *string `json:"tokenType,omitempty"`
	// RefreshCache forces a metadata refresh.
	RefreshCache bool `json:"refreshCache,omitempty"`
}

NFTMetadataParams represents the parameters for getNFTMetadata.

func NewNFTMetadataParams

func NewNFTMetadataParams(contractAddress types.Address, tokenID string) *NFTMetadataParams

NewNFTMetadataParams creates new NFTMetadataParams.

func (*NFTMetadataParams) SetRefreshCache

func (p *NFTMetadataParams) SetRefreshCache(refresh bool) *NFTMetadataParams

SetRefreshCache enables cache refresh.

func (*NFTMetadataParams) SetTokenType

func (p *NFTMetadataParams) SetTokenType(tokenType string) *NFTMetadataParams

SetTokenType sets the token type.

type NFTOrderBy

type NFTOrderBy string

NFTOrderBy represents the ordering for NFT results.

const (
	NFTOrderByTransferTime NFTOrderBy = "transferTime"
)

NFT order options.

type NFTRaw

type NFTRaw struct {
	// TokenURI is the raw token URI.
	TokenURI *string `json:"tokenUri,omitempty"`
	// Metadata contains raw metadata.
	Metadata *NFTRawMetadata `json:"metadata,omitempty"`
	// Error is any error during metadata fetch.
	Error *string `json:"error,omitempty"`
}

NFTRaw contains raw NFT data.

type NFTRawMetadata

type NFTRawMetadata struct {
	// Image is the image URL.
	Image *string `json:"image,omitempty"`
	// Name is the NFT name.
	Name *string `json:"name,omitempty"`
	// Description is the NFT description.
	Description *string `json:"description,omitempty"`
	// Attributes is the list of attributes.
	Attributes []NFTAttribute `json:"attributes,omitempty"`
	// ExternalURL is the external URL.
	ExternalURL *string `json:"external_url,omitempty"`
	// AnimationURL is the animation URL.
	AnimationURL *string `json:"animation_url,omitempty"`
}

NFTRawMetadata contains raw NFT metadata.

type NFTTokenType

type NFTTokenType string

NFTTokenType represents the type of NFT token.

const (
	NFTTokenTypeERC721  NFTTokenType = "ERC721"
	NFTTokenTypeERC1155 NFTTokenType = "ERC1155"
)

NFT token types.

type NFTWebhookFilter

type NFTWebhookFilter struct {
	// ContractAddress is the NFT contract address to track.
	ContractAddress string `json:"contract_address"`
	// TokenID is the specific token ID to track (optional, tracks all if empty).
	TokenID *string `json:"token_id,omitempty"`
}

NFTWebhookFilter represents a filter for NFT activity webhooks.

type NFTWebhookFiltersResponse

type NFTWebhookFiltersResponse struct {
	// Data contains the list of NFT filters.
	Data []NFTWebhookFilter `json:"data"`
	// Pagination contains pagination information.
	Pagination WebhookPagination `json:"pagination"`
}

NFTWebhookFiltersResponse represents the response from getting NFT webhook filters.

type NFTsForContractResponse

type NFTsForContractResponse struct {
	// NFTs is the list of NFTs in the contract.
	NFTs []OwnedNFT `json:"nfts"`
	// PageKey is the pagination key.
	PageKey string `json:"pageKey,omitempty"`
}

NFTsForContractResponse represents the response from getNFTsForContract.

func (*NFTsForContractResponse) HasMore

func (r *NFTsForContractResponse) HasMore() bool

HasMore returns true if there are more results available.

type NFTsForOwnerIterator

type NFTsForOwnerIterator struct {
	// contains filtered or unexported fields
}

NFTsForOwnerIterator iterates through NFTs with pagination.

func (*NFTsForOwnerIterator) Collect

func (it *NFTsForOwnerIterator) Collect() ([]OwnedNFT, error)

Collect returns all remaining NFTs as a slice.

func (*NFTsForOwnerIterator) Error

func (it *NFTsForOwnerIterator) Error() error

Error returns any error encountered during iteration.

func (*NFTsForOwnerIterator) HasNext

func (it *NFTsForOwnerIterator) HasNext() bool

HasNext returns true if there are more NFTs to iterate.

func (*NFTsForOwnerIterator) Next

func (it *NFTsForOwnerIterator) Next() (*OwnedNFT, error)

Next returns the next NFT in the iteration.

func (*NFTsForOwnerIterator) TotalCount

func (it *NFTsForOwnerIterator) TotalCount() int

TotalCount returns the total count of NFTs (available after first fetch).

type NFTsForOwnerParams

type NFTsForOwnerParams struct {
	// Owner is the address of the NFT owner.
	Owner types.Address `json:"owner"`
	// ContractAddresses filters NFTs by contract addresses (max 45).
	ContractAddresses []types.Address `json:"contractAddresses,omitempty"`
	// WithMetadata includes NFT metadata in the response.
	WithMetadata *bool `json:"withMetadata,omitempty"`
	// OrderBy specifies the ordering of results.
	OrderBy NFTOrderBy `json:"orderBy,omitempty"`
	// ExcludeFilters excludes NFTs matching these filters.
	ExcludeFilters []NFTFilter `json:"excludeFilters,omitempty"`
	// IncludeFilters includes only NFTs matching these filters.
	IncludeFilters []NFTFilter `json:"includeFilters,omitempty"`
	// SpamConfidenceLevel sets the spam detection threshold.
	SpamConfidenceLevel SpamConfidenceLevel `json:"spamConfidenceLevel,omitempty"`
	// TokenURITimeoutInMs sets the timeout for fetching token URIs.
	TokenURITimeoutInMs *int `json:"tokenUriTimeoutInMs,omitempty"`
	// PageKey is the pagination key.
	PageKey string `json:"pageKey,omitempty"`
	// PageSize is the number of results per page (max 100).
	PageSize *int `json:"pageSize,omitempty"`
}

NFTsForOwnerParams represents the parameters for getNFTsForOwner.

func NewNFTsForOwnerParams

func NewNFTsForOwnerParams(owner types.Address) *NFTsForOwnerParams

NewNFTsForOwnerParams creates new NFTsForOwnerParams.

func (*NFTsForOwnerParams) SetContractAddresses

func (p *NFTsForOwnerParams) SetContractAddresses(addresses []types.Address) *NFTsForOwnerParams

SetContractAddresses sets the contract address filter.

func (*NFTsForOwnerParams) SetExcludeFilters

func (p *NFTsForOwnerParams) SetExcludeFilters(filters []NFTFilter) *NFTsForOwnerParams

SetExcludeFilters sets exclusion filters.

func (*NFTsForOwnerParams) SetOrderBy

func (p *NFTsForOwnerParams) SetOrderBy(orderBy NFTOrderBy) *NFTsForOwnerParams

SetOrderBy sets the ordering.

func (*NFTsForOwnerParams) SetPageSize

func (p *NFTsForOwnerParams) SetPageSize(size int) *NFTsForOwnerParams

SetPageSize sets the page size.

func (*NFTsForOwnerParams) SetWithMetadata

func (p *NFTsForOwnerParams) SetWithMetadata(withMetadata bool) *NFTsForOwnerParams

SetWithMetadata enables metadata in the response.

type NFTsForOwnerResponse

type NFTsForOwnerResponse struct {
	// OwnedNFTs is the list of owned NFTs.
	OwnedNFTs []OwnedNFT `json:"ownedNfts"`
	// TotalCount is the total number of NFTs.
	TotalCount int `json:"totalCount"`
	// PageKey is the pagination key.
	PageKey string `json:"pageKey,omitempty"`
	// ValidAt contains block information.
	ValidAt *ValidAt `json:"validAt,omitempty"`
}

NFTsForOwnerResponse represents the response from getNFTsForOwner.

func (*NFTsForOwnerResponse) HasMore

func (r *NFTsForOwnerResponse) HasMore() bool

HasMore returns true if there are more results available.

type OpenSeaMetadata

type OpenSeaMetadata struct {
	// FloorPrice is the floor price.
	FloorPrice *float64 `json:"floorPrice,omitempty"`
	// CollectionName is the collection name.
	CollectionName *string `json:"collectionName,omitempty"`
	// SafelistRequestStatus is the safelist status.
	SafelistRequestStatus *string `json:"safelistRequestStatus,omitempty"`
	// ImageURL is the collection image URL.
	ImageURL *string `json:"imageUrl,omitempty"`
	// Description is the collection description.
	Description *string `json:"description,omitempty"`
	// ExternalURL is the external URL.
	ExternalURL *string `json:"externalUrl,omitempty"`
	// TwitterUsername is the Twitter username.
	TwitterUsername *string `json:"twitterUsername,omitempty"`
	// DiscordURL is the Discord URL.
	DiscordURL *string `json:"discordUrl,omitempty"`
	// BannerImageURL is the banner image URL.
	BannerImageURL *string `json:"bannerImageUrl,omitempty"`
	// LastIngestedAt is when the metadata was last ingested.
	LastIngestedAt *string `json:"lastIngestedAt,omitempty"`
}

OpenSeaMetadata contains OpenSea-specific metadata.

type OwnedNFT

type OwnedNFT struct {
	// Contract contains contract information.
	Contract NFTContract `json:"contract"`
	// TokenID is the token ID.
	TokenID string `json:"tokenId"`
	// TokenType is the token type (ERC721, ERC1155).
	TokenType string `json:"tokenType"`
	// Name is the NFT name.
	Name *string `json:"name,omitempty"`
	// Description is the NFT description.
	Description *string `json:"description,omitempty"`
	// Image contains image information.
	Image *NFTImage `json:"image,omitempty"`
	// Raw contains raw token data.
	Raw *NFTRaw `json:"raw,omitempty"`
	// Collection contains collection information.
	Collection *NFTCollection `json:"collection,omitempty"`
	// TokenURI is the token URI.
	TokenURI *string `json:"tokenUri,omitempty"`
	// TimeLastUpdated is when the metadata was last updated.
	TimeLastUpdated *string `json:"timeLastUpdated,omitempty"`
	// AcquiredAt contains acquisition information.
	AcquiredAt *AcquiredAt `json:"acquiredAt,omitempty"`
	// Balance is the token balance (for ERC1155).
	Balance *string `json:"balance,omitempty"`
}

OwnedNFT represents an NFT owned by an address.

type OwnedToken

type OwnedToken struct {
	// ContractAddress is the token contract address.
	ContractAddress types.Address `json:"contractAddress"`
	// RawBalance is the raw balance (hex encoded).
	RawBalance string `json:"rawBalance"`
	// Balance is the formatted balance.
	Balance string `json:"balance"`
	// Name is the token name.
	Name *string `json:"name,omitempty"`
	// Symbol is the token symbol.
	Symbol *string `json:"symbol,omitempty"`
	// Decimals is the number of decimals.
	Decimals *int `json:"decimals,omitempty"`
	Logo *string `json:"logo,omitempty"`
	// Error is the error message if there was an issue.
	Error *string `json:"error,omitempty"`
}

OwnedToken represents a token owned by an address.

type OwnersForContractResponse

type OwnersForContractResponse struct {
	// Owners is the list of owners with their balances.
	Owners []ContractOwner `json:"ownerAddresses"`
	// PageKey is the pagination key.
	PageKey string `json:"pageKey,omitempty"`
}

OwnersForContractResponse represents the response from getOwnersForContract.

type OwnersForNFTResponse

type OwnersForNFTResponse struct {
	// Owners is the list of owner addresses.
	Owners []types.Address `json:"owners"`
	// PageKey is the pagination key.
	PageKey string `json:"pageKey,omitempty"`
}

OwnersForNFTResponse represents the response from getOwnersForNFT.

type RawContract

type RawContract struct {
	// Value is the raw transfer value (hex).
	Value *string `json:"value,omitempty"`
	// Address is the contract address.
	Address *string `json:"address,omitempty"`
	// Decimal is the token decimals (hex).
	Decimal *string `json:"decimal,omitempty"`
}

RawContract contains raw contract information.

type RawContractInfo

type RawContractInfo struct {
	// RawValue is the raw value (hex).
	RawValue string `json:"rawValue"`
	// Address is the contract address.
	Address string `json:"address"`
	// Decimals is the token decimals.
	Decimals int `json:"decimals"`
}

RawContractInfo contains raw contract information.

type ReplaceWebhookAddressesParams

type ReplaceWebhookAddressesParams struct {
	// WebhookID is the ID of the webhook.
	WebhookID string `json:"webhook_id"`
	// Addresses is the new list of addresses (replaces all existing addresses).
	Addresses []string `json:"addresses"`
}

ReplaceWebhookAddressesParams represents the parameters for replacing webhook addresses.

type SortOrder

type SortOrder string

SortOrder represents the sort order for results.

const (
	SortAsc  SortOrder = "asc"
	SortDesc SortOrder = "desc"
)

Sort orders.

type SpamConfidenceLevel

type SpamConfidenceLevel string

SpamConfidenceLevel represents the spam confidence level.

const (
	SpamConfidenceVeryHigh SpamConfidenceLevel = "VERY_HIGH"
	SpamConfidenceHigh     SpamConfidenceLevel = "HIGH"
	SpamConfidenceMedium   SpamConfidenceLevel = "MEDIUM"
	SpamConfidenceLow      SpamConfidenceLevel = "LOW"
)

Spam confidence levels.

type TokenAllowanceParams

type TokenAllowanceParams struct {
	// Contract is the token contract address.
	Contract types.Address `json:"contract"`
	// Owner is the owner address.
	Owner types.Address `json:"owner"`
	// Spender is the spender address.
	Spender types.Address `json:"spender"`
}

TokenAllowanceParams represents the parameters for getTokenAllowance.

type TokenAllowanceResponse

type TokenAllowanceResponse struct {
	// Allowance is the allowance amount (hex encoded).
	Allowance string `json:"allowance"`
}

TokenAllowanceResponse represents the response from getTokenAllowance.

type TokenBalance

type TokenBalance struct {
	// ContractAddress is the token contract address.
	ContractAddress types.Address `json:"contractAddress"`
	// TokenBalance is the balance in the smallest unit (hex encoded).
	TokenBalance *string `json:"tokenBalance,omitempty"`
	// Error is the error message if the balance couldn't be fetched.
	Error *string `json:"error,omitempty"`
}

TokenBalance represents a single token balance.

func (*TokenBalance) HasError

func (b *TokenBalance) HasError() bool

HasError returns true if there was an error fetching the balance.

type TokenBalanceEntry

type TokenBalanceEntry struct {
	// TokenID is the token ID.
	TokenID string `json:"tokenId"`
	// Balance is the balance.
	Balance string `json:"balance"`
}

TokenBalanceEntry represents a token balance entry.

type TokenBalancesParams

type TokenBalancesParams struct {
	// Address is the wallet address to query.
	Address types.Address `json:"address"`
	// TokenSpec is the type of tokens to query (optional).
	TokenSpec TokenSpec `json:"tokenSpec,omitempty"`
	// ContractAddresses is a list of specific contract addresses to query (optional).
	ContractAddresses []types.Address `json:"contractAddresses,omitempty"`
	// PageKey is the pagination key for fetching more results.
	PageKey string `json:"pageKey,omitempty"`
	// MaxCount is the maximum number of results per page.
	MaxCount int `json:"maxCount,omitempty"`
}

TokenBalancesParams represents the parameters for getTokenBalances.

func NewTokenBalancesParams

func NewTokenBalancesParams(address types.Address) *TokenBalancesParams

NewTokenBalancesParams creates a new TokenBalancesParams.

func (*TokenBalancesParams) SetContractAddresses

func (p *TokenBalancesParams) SetContractAddresses(addresses []types.Address) *TokenBalancesParams

SetContractAddresses sets specific contract addresses to query.

func (*TokenBalancesParams) SetMaxCount

func (p *TokenBalancesParams) SetMaxCount(count int) *TokenBalancesParams

SetMaxCount sets the maximum number of results.

func (*TokenBalancesParams) SetTokenSpec

func (p *TokenBalancesParams) SetTokenSpec(spec TokenSpec) *TokenBalancesParams

SetTokenSpec sets the token specification.

type TokenBalancesResponse

type TokenBalancesResponse struct {
	// Address is the queried address.
	Address types.Address `json:"address"`
	// TokenBalances is the list of token balances.
	TokenBalances []TokenBalance `json:"tokenBalances"`
	// PageKey is the pagination key for fetching more results.
	PageKey string `json:"pageKey,omitempty"`
}

TokenBalancesResponse represents the response from getTokenBalances.

func (*TokenBalancesResponse) HasMore

func (r *TokenBalancesResponse) HasMore() bool

HasMore returns true if there are more results available.

type TokenMetadata

type TokenMetadata struct {
	// Name is the token name.
	Name *string `json:"name,omitempty"`
	// Symbol is the token symbol.
	Symbol *string `json:"symbol,omitempty"`
	// Decimals is the number of decimals.
	Decimals *int `json:"decimals,omitempty"`
	Logo *string `json:"logo,omitempty"`
}

TokenMetadata represents token metadata.

type TokenSpec

type TokenSpec string

TokenSpec represents the type of token to query.

const (
	TokenSpecERC20       TokenSpec = "erc20"
	TokenSpecNativeToken TokenSpec = "NATIVE_TOKEN"
)

Token specifications.

type TokensForOwnerResponse

type TokensForOwnerResponse struct {
	// Tokens is the list of tokens owned by the address.
	Tokens []OwnedToken `json:"tokens"`
	// PageKey is the pagination key for fetching more results.
	PageKey string `json:"pageKey,omitempty"`
}

TokensForOwnerResponse represents the response from getTokensForOwner.

func (*TokensForOwnerResponse) HasMore

func (r *TokensForOwnerResponse) HasMore() bool

HasMore returns true if there are more results available.

type TransferMetadata

type TransferMetadata struct {
	// BlockTimestamp is the block timestamp in ISO format.
	BlockTimestamp string `json:"blockTimestamp"`
}

TransferMetadata contains additional transfer metadata.

type UpdateNFTFiltersParams

type UpdateNFTFiltersParams struct {
	// WebhookID is the ID of the webhook.
	WebhookID string `json:"webhook_id"`
	// FiltersToAdd is the list of filters to add.
	FiltersToAdd []NFTWebhookFilter `json:"nft_filters_to_add"`
	// FiltersToRemove is the list of filters to remove.
	FiltersToRemove []NFTWebhookFilter `json:"nft_filters_to_remove"`
}

UpdateNFTFiltersParams represents the parameters for updating NFT webhook filters.

type UpdateWebhookAddressesParams

type UpdateWebhookAddressesParams struct {
	// WebhookID is the ID of the webhook.
	WebhookID string `json:"webhook_id"`
	// AddressesToAdd is the list of addresses to add.
	AddressesToAdd []string `json:"addresses_to_add"`
	// AddressesToRemove is the list of addresses to remove.
	AddressesToRemove []string `json:"addresses_to_remove"`
}

UpdateWebhookAddressesParams represents the parameters for updating webhook addresses.

func NewUpdateWebhookAddressesParams

func NewUpdateWebhookAddressesParams(webhookID string) *UpdateWebhookAddressesParams

NewUpdateWebhookAddressesParams creates parameters for updating webhook addresses.

func (*UpdateWebhookAddressesParams) AddAddresses

func (p *UpdateWebhookAddressesParams) AddAddresses(addresses ...string) *UpdateWebhookAddressesParams

AddAddresses adds addresses to track.

func (*UpdateWebhookAddressesParams) RemoveAddresses

func (p *UpdateWebhookAddressesParams) RemoveAddresses(addresses ...string) *UpdateWebhookAddressesParams

RemoveAddresses removes addresses from tracking.

type UpdateWebhookParams

type UpdateWebhookParams struct {
	// WebhookID is the ID of the webhook to update.
	WebhookID string `json:"webhook_id"`
	// IsActive sets whether the webhook is active.
	IsActive *bool `json:"is_active,omitempty"`
	// Name sets the webhook name.
	Name *string `json:"name,omitempty"`
}

UpdateWebhookParams represents the parameters for updating a webhook.

func NewUpdateWebhookParams

func NewUpdateWebhookParams(webhookID string) *UpdateWebhookParams

NewUpdateWebhookParams creates parameters for updating a webhook.

func (*UpdateWebhookParams) SetActive

func (p *UpdateWebhookParams) SetActive(active bool) *UpdateWebhookParams

SetActive sets the webhook active status.

func (*UpdateWebhookParams) SetName

SetName sets the webhook name.

type UpdateWebhookResponse

type UpdateWebhookResponse struct {
	// Data contains the updated webhook.
	Data Webhook `json:"data"`
}

UpdateWebhookResponse represents the response from updating a webhook.

type ValidAt

type ValidAt struct {
	// BlockNumber is the block number.
	BlockNumber int `json:"blockNumber"`
	// BlockHash is the block hash.
	BlockHash string `json:"blockHash"`
	// BlockTimestamp is the block timestamp.
	BlockTimestamp string `json:"blockTimestamp"`
}

ValidAt contains block validity information.

type Webhook

type Webhook struct {
	// ID is the unique identifier for the webhook.
	ID string `json:"id"`
	// Network is the blockchain network.
	Network WebhookNetwork `json:"network"`
	// WebhookType is the type of webhook.
	WebhookType WebhookType `json:"webhook_type"`
	// WebhookURL is the URL where webhook events are sent.
	WebhookURL string `json:"webhook_url"`
	// IsActive indicates whether the webhook is active.
	IsActive bool `json:"is_active"`
	// TimeCreated is the Unix timestamp when the webhook was created.
	TimeCreated int64 `json:"time_created"`
	// Version is the webhook payload version (V1 or V2).
	Version WebhookVersion `json:"version"`
	// SigningKey is the key used to sign webhook payloads.
	SigningKey string `json:"signing_key"`
	// AppID is the associated app ID (optional).
	AppID *string `json:"app_id,omitempty"`
	// Name is the webhook name (optional).
	Name *string `json:"name,omitempty"`
}

Webhook represents an Alchemy webhook configuration.

type WebhookClient

type WebhookClient struct {
	// contains filtered or unexported fields
}

WebhookClient provides access to Alchemy Webhook (Notify) API. It requires an auth token obtained from the Alchemy dashboard.

func NewWebhookClient

func NewWebhookClient(authToken string, httpClient *http.Client) *WebhookClient

NewWebhookClient creates a new WebhookClient.

func (*WebhookClient) CreateWebhook

func (c *WebhookClient) CreateWebhook(ctx context.Context, params *CreateWebhookParams) (*CreateWebhookResponse, error)

CreateWebhook creates a new webhook.

func (*WebhookClient) DeleteWebhook

func (c *WebhookClient) DeleteWebhook(ctx context.Context, webhookID string) error

DeleteWebhook deletes a webhook.

func (*WebhookClient) GetAllWebhookAddresses

func (c *WebhookClient) GetAllWebhookAddresses(ctx context.Context, webhookID string) ([]string, error)

GetAllWebhookAddresses retrieves all addresses tracked by a webhook (handles pagination).

func (*WebhookClient) GetAllWebhooks

func (c *WebhookClient) GetAllWebhooks(ctx context.Context) (*GetWebhooksResponse, error)

GetAllWebhooks retrieves all webhooks for the team.

func (*WebhookClient) GetNFTFilters

func (c *WebhookClient) GetNFTFilters(ctx context.Context, webhookID string, limit int, after string) (*NFTWebhookFiltersResponse, error)

GetNFTFilters retrieves NFT filters for a webhook.

func (*WebhookClient) GetWebhookAddresses

GetWebhookAddresses retrieves addresses tracked by a webhook.

func (*WebhookClient) ReplaceWebhookAddresses

func (c *WebhookClient) ReplaceWebhookAddresses(ctx context.Context, params *ReplaceWebhookAddressesParams) error

ReplaceWebhookAddresses replaces all addresses tracked by a webhook.

func (*WebhookClient) UpdateNFTFilters

func (c *WebhookClient) UpdateNFTFilters(ctx context.Context, params *UpdateNFTFiltersParams) error

UpdateNFTFilters adds or removes NFT filters from a webhook.

func (*WebhookClient) UpdateWebhook

func (c *WebhookClient) UpdateWebhook(ctx context.Context, params *UpdateWebhookParams) (*UpdateWebhookResponse, error)

UpdateWebhook updates a webhook's status or name.

func (*WebhookClient) UpdateWebhookAddresses

func (c *WebhookClient) UpdateWebhookAddresses(ctx context.Context, params *UpdateWebhookAddressesParams) error

UpdateWebhookAddresses adds or removes addresses from a webhook.

type WebhookCursors

type WebhookCursors struct {
	// After is the cursor pointing to the end of the current result set.
	After string `json:"after"`
}

WebhookCursors represents pagination cursors.

type WebhookEvent

type WebhookEvent struct {
	// WebhookID is the unique identifier for the webhook.
	WebhookID string `json:"webhookId"`
	// ID is the event ID.
	ID string `json:"id"`
	// CreatedAt is when the event was created.
	CreatedAt string `json:"createdAt"`
	// Type is the event type.
	Type string `json:"type"`
	// Event contains the event data.
	Event interface{} `json:"event"`
}

WebhookEvent represents a webhook event payload (V2 format).

func ParseWebhookEvent

func ParseWebhookEvent(body []byte) (*WebhookEvent, error)

ParseWebhookEvent parses a webhook event from the request body.

type WebhookNetwork

type WebhookNetwork string

WebhookNetwork represents the network for a webhook.

const (
	// Ethereum
	WebhookNetworkEthMainnet WebhookNetwork = "ETH_MAINNET"
	WebhookNetworkEthSepolia WebhookNetwork = "ETH_SEPOLIA"
	WebhookNetworkEthHolesky WebhookNetwork = "ETH_HOLESKY"

	// Polygon
	WebhookNetworkPolygonMainnet WebhookNetwork = "MATIC_MAINNET"
	WebhookNetworkPolygonAmoy    WebhookNetwork = "MATIC_AMOY"

	// Arbitrum
	WebhookNetworkArbitrumMainnet WebhookNetwork = "ARB_MAINNET"
	WebhookNetworkArbitrumSepolia WebhookNetwork = "ARB_SEPOLIA"

	// Optimism
	WebhookNetworkOptimismMainnet WebhookNetwork = "OPT_MAINNET"
	WebhookNetworkOptimismSepolia WebhookNetwork = "OPT_SEPOLIA"

	// Base
	WebhookNetworkBaseMainnet WebhookNetwork = "BASE_MAINNET"
	WebhookNetworkBaseSepolia WebhookNetwork = "BASE_SEPOLIA"

	// zkSync
	WebhookNetworkZkSyncMainnet WebhookNetwork = "ZKSYNC_MAINNET"
	WebhookNetworkZkSyncSepolia WebhookNetwork = "ZKSYNC_SEPOLIA"
)

Webhook networks.

type WebhookPagination

type WebhookPagination struct {
	// Cursors contains pagination cursors.
	Cursors WebhookCursors `json:"cursors"`
	// TotalCount is the total number of items.
	TotalCount int `json:"total_count"`
}

WebhookPagination represents pagination information.

type WebhookType

type WebhookType string

WebhookType represents the type of webhook.

const (
	WebhookTypeGraphQL         WebhookType = "GRAPHQL"
	WebhookTypeAddressActivity WebhookType = "ADDRESS_ACTIVITY"
	WebhookTypeNFTActivity     WebhookType = "NFT_ACTIVITY"
)

Webhook types.

type WebhookVersion

type WebhookVersion string

WebhookVersion represents the version of webhook payload format.

const (
	WebhookVersionV1 WebhookVersion = "V1"
	WebhookVersionV2 WebhookVersion = "V2"
)

Webhook versions.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL