Skip to content

LeoYeAI/agent-master-skills / skills/alchemy-official

alchemy-official

Verified

FileKindSize
AGENTIC-GATEWAY.mdmarkdown4.3 KB
SKILL.mdskill md24.0 KB
SOURCE.mdmarkdown188 B
_meta.jsonconfig466 B
references/data-nft-api.mdmarkdown15.8 KB
references/data-overview.mdmarkdown2.0 KB
references/data-portfolio-apis.mdmarkdown15.9 KB
references/data-prices-api.mdmarkdown6.3 KB
references/data-simulation-api.mdmarkdown10.2 KB
references/data-token-api.mdmarkdown5.4 KB
references/data-transfers-api.mdmarkdown5.1 KB
references/ecosystem-anchor.mdmarkdown632 B
references/ecosystem-ethers.mdmarkdown772 B
references/ecosystem-foundry.mdmarkdown654 B
references/ecosystem-hardhat.mdmarkdown795 B
references/ecosystem-metaplex.mdmarkdown652 B
references/ecosystem-overview.mdmarkdown2.3 KB
references/ecosystem-rainbowkit.mdmarkdown604 B
references/ecosystem-solana-web3js.mdmarkdown766 B
references/ecosystem-spl-token.mdmarkdown737 B
references/ecosystem-viem.mdmarkdown827 B
references/ecosystem-wagmi.mdmarkdown829 B
references/ecosystem-web3js.mdmarkdown689 B
references/node-debug-api.mdmarkdown5.0 KB
references/node-enhanced-apis.mdmarkdown2.7 KB
references/node-json-rpc.mdmarkdown10.4 KB
references/node-overview.mdmarkdown2.1 KB
references/node-trace-api.mdmarkdown5.7 KB
references/node-utility-api.mdmarkdown3.1 KB
references/node-websocket-subscriptions.mdmarkdown4.1 KB
references/operational-alerts.mdmarkdown765 B
references/operational-allowlists.mdmarkdown819 B
references/operational-auth-and-keys.mdmarkdown1.1 KB
references/operational-best-practices.mdmarkdown1.0 KB
references/operational-dashboard-tools.mdmarkdown700 B
references/operational-jwt-and-header-auth.mdmarkdown1.1 KB
references/operational-overview.mdmarkdown2.0 KB
references/operational-pricing-and-plans.mdmarkdown916 B
references/operational-rate-limits-and-compute-units.mdmarkdown1.1 KB
references/operational-request-logs.mdmarkdown680 B
references/operational-roles-and-sso.mdmarkdown686 B
references/operational-sandbox.mdmarkdown686 B
references/operational-supported-networks.mdmarkdown2.3 KB
references/recipes-get-nft-metadata.mdmarkdown1.2 KB
references/recipes-get-nft-ownership.mdmarkdown1.2 KB
references/recipes-get-portfolio.mdmarkdown1.5 KB
references/recipes-get-prices-current-historical.mdmarkdown1.1 KB
references/recipes-get-token-balances.mdmarkdown1.4 KB
references/recipes-get-token-metadata.mdmarkdown1.3 KB
references/recipes-get-transfers-history.mdmarkdown1.0 KB
references/recipes-overview.mdmarkdown1.4 KB
references/recipes-simulate-transaction.mdmarkdown1.1 KB
references/recipes-subscribe-pending-txs.mdmarkdown1.7 KB
references/recipes-webhook-address-activity.mdmarkdown1.4 KB
references/rollups-details.mdmarkdown1.1 KB
references/rollups-overview.mdmarkdown793 B
references/solana-das-api.mdmarkdown9.0 KB
references/solana-grpc-best-practices.mdmarkdown896 B
references/solana-grpc-details.mdmarkdown1.0 KB
references/solana-grpc-examples.mdmarkdown958 B
references/solana-grpc-overview.mdmarkdown1.5 KB
references/solana-grpc-subscribe-accounts.mdmarkdown733 B
references/solana-grpc-subscribe-blocks.mdmarkdown739 B
references/solana-grpc-subscribe-request.mdmarkdown969 B
references/solana-grpc-subscribe-slots.mdmarkdown642 B
references/solana-grpc-subscribe-transactions.mdmarkdown890 B
references/solana-overview.mdmarkdown1.3 KB
references/solana-rpc.mdmarkdown7.2 KB
references/solana-wallets.mdmarkdown921 B
references/wallets-account-kit.mdmarkdown1.2 KB
references/wallets-bundler.mdmarkdown832 B
references/wallets-details.mdmarkdown1.1 KB
references/wallets-gas-manager.mdmarkdown799 B
references/wallets-overview.mdmarkdown1.6 KB
references/wallets-smart-wallets.mdmarkdown1.1 KB
references/wallets-solana-notes.mdmarkdown692 B
references/wallets-supported-chains.mdmarkdown737 B
references/wallets-wallet-apis.mdmarkdown1.0 KB
references/webhooks-address-activity.mdmarkdown1.5 KB
references/webhooks-custom-webhooks.mdmarkdown1.2 KB
references/webhooks-details.mdmarkdown2.5 KB
references/webhooks-nft-activity.mdmarkdown1.4 KB
references/webhooks-overview.mdmarkdown1.5 KB
references/webhooks-verify-signatures.mdmarkdown1.5 KB
references/webhooks-webhook-payloads.mdmarkdown1.1 KB
references/webhooks-webhook-types.mdmarkdown1.0 KB
rules/authentication.mdmarkdown4.5 KB
rules/curl-workflow.mdmarkdown8.5 KB
rules/making-requests.mdmarkdown5.6 KB
rules/overview.mdmarkdown2.2 KB
rules/payment.mdmarkdown3.4 KB
rules/reference.mdmarkdown5.0 KB
rules/wallet-bootstrap.mdmarkdown2.4 KB

references/data-nft-api.md

View on GitHub
---
id: references/data-nft-api.md
name: 'NFT API'
description: 'Query NFT ownership, metadata, collections, and contract-level info via Alchemy''s NFT REST APIs.'
tags:
  - alchemy
  - data-apis
  - data
related:
  - recipes-get-nft-ownership.md
  - recipes-get-nft-metadata.md
updated: 2026-02-23
---
# NFT API

Query NFT ownership, metadata, collections, and contract-level info. REST endpoints (GET).

**Base URL**: `https://<network>.g.alchemy.com/nft/v3/$ALCHEMY_API_KEY`

**Supported chains**: Ethereum, Base, Polygon, Arbitrum, Optimism, BNB, and testnets.

---

## `GET /getNFTsForOwner`

Returns all NFTs owned by a given address.

### Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `owner` | string (query) | Yes | — | Wallet address |
| `contractAddresses[]` | string[] (query) | No | — | Filter by contract addresses (max 45) |
| `withMetadata` | boolean (query) | No | `true` | Include metadata in response |
| `orderBy` | string (query) | No | — | `"transferTime"` to sort by acquisition time |
| `excludeFilters[]` | string[] (query) | No | — | `"SPAM"`, `"AIRDROPS"` |
| `includeFilters[]` | string[] (query) | No | — | `"SPAM"`, `"AIRDROPS"` |
| `spamConfidenceLevel` | string (query) | No | — | `"VERY_HIGH"`, `"HIGH"`, `"MEDIUM"`, `"LOW"` |
| `tokenUriTimeoutInMs` | integer (query) | No | — | Timeout for token URI resolution |
| `pageKey` | string (query) | No | — | Pagination cursor |
| `pageSize` | integer (query) | No | `100` | Results per page (max 100) |

### Request

```bash
curl -s "https://eth-mainnet.g.alchemy.com/nft/v3/$ALCHEMY_API_KEY/getNFTsForOwner?owner=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045&withMetadata=true&pageSize=2"
```

### Response

```json
{
  "ownedNfts": [
    {
      "contract": {
        "address": "0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d",
        "name": "BoredApeYachtClub",
        "symbol": "BAYC",
        "totalSupply": "10000",
        "tokenType": "ERC721",
        "contractDeployer": "0xaba7161a7fb69c88e16ed9f455ce62b791ee4d03",
        "deployedBlockNumber": 12287507,
        "openSeaMetadata": {
          "collectionName": "Bored Ape Yacht Club",
          "collectionSlug": "boredapeyachtclub",
          "safelistRequestStatus": "verified",
          "imageUrl": "https://...",
          "description": "...",
          "floorPrice": 10.5
        },
        "isSpam": false,
        "spamClassifications": []
      },
      "tokenId": "1234",
      "tokenType": "ERC721",
      "name": "Bored Ape #1234",
      "description": "...",
      "tokenUri": "ipfs://Qm.../1234",
      "image": {
        "cachedUrl": "https://nft-cdn.alchemy.com/...",
        "thumbnailUrl": "https://nft-cdn.alchemy.com/...",
        "pngUrl": "https://nft-cdn.alchemy.com/...",
        "contentType": "image/png",
        "size": 123456,
        "originalUrl": "ipfs://..."
      },
      "animation": {
        "cachedUrl": null,
        "contentType": null,
        "size": null,
        "originalUrl": null
      },
      "raw": {
        "tokenUri": "ipfs://Qm.../1234",
        "metadata": { "name": "Bored Ape #1234", "image": "ipfs://...", "attributes": [] },
        "error": null
      },
      "collection": {
        "name": "Bored Ape Yacht Club",
        "slug": "boredapeyachtclub",
        "externalUrl": "https://boredapeyachtclub.com",
        "bannerImageUrl": "https://..."
      },
      "mint": {
        "mintAddress": null,
        "blockNumber": null,
        "timestamp": null,
        "transactionHash": null
      },
      "owners": null,
      "timeLastUpdated": "2025-06-01T12:00:00.000Z",
      "balance": "1",
      "acquiredAt": {
        "blockTimestamp": "2024-03-15T10:30:00.000Z",
        "blockNumber": "19445200"
      }
    }
  ],
  "totalCount": 42,
  "validAt": {
    "blockNumber": "20000000",
    "blockHash": "0x...",
    "blockTimestamp": "2025-06-01T12:00:00.000Z"
  },
  "pageKey": "abc123..."
}
```

### Response Fields

| Field | Type | Description |
|-------|------|-------------|
| `ownedNfts` | array | List of NFT objects |
| `ownedNfts[].contract.address` | string | Contract address |
| `ownedNfts[].contract.name` | string | Collection name |
| `ownedNfts[].contract.symbol` | string | Collection symbol |
| `ownedNfts[].contract.tokenType` | string | `"ERC721"` or `"ERC1155"` |
| `ownedNfts[].contract.openSeaMetadata` | object | OpenSea collection data (name, slug, floor price, etc.) |
| `ownedNfts[].contract.isSpam` | boolean | Whether contract is flagged as spam |
| `ownedNfts[].tokenId` | string | Token ID |
| `ownedNfts[].tokenType` | string | `"ERC721"` or `"ERC1155"` |
| `ownedNfts[].name` | string | NFT name (from metadata) |
| `ownedNfts[].description` | string | NFT description |
| `ownedNfts[].tokenUri` | string | Resolved token URI |
| `ownedNfts[].image` | object | Image URLs (cachedUrl, thumbnailUrl, pngUrl, originalUrl) |
| `ownedNfts[].animation` | object | Animation URLs (cachedUrl, contentType, size, originalUrl) |
| `ownedNfts[].raw.metadata` | object | Raw metadata JSON |
| `ownedNfts[].collection` | object | Collection info (name, slug, externalUrl) |
| `ownedNfts[].mint` | object | Minting info (mintAddress, blockNumber, timestamp, transactionHash) |
| `ownedNfts[].owners` | array | Current owners (may be null) |
| `ownedNfts[].balance` | string | Token balance (always `"1"` for ERC-721) |
| `ownedNfts[].acquiredAt` | object | Acquisition timestamp and block number |
| `totalCount` | integer | Total NFTs owned (across all pages) |
| `validAt` | object | Block at which data is valid |
| `pageKey` | string | Cursor for next page (absent if no more results) |

---

## `GET /getNFTMetadata`

Returns metadata for a single NFT.

### Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `contractAddress` | string (query) | Yes | — | NFT contract address |
| `tokenId` | string (query) | Yes | — | Token ID |
| `tokenType` | string (query) | No | — | `"ERC721"` or `"ERC1155"` (auto-detected if omitted) |
| `tokenUriTimeoutInMs` | integer (query) | No | — | Timeout for token URI resolution |
| `refreshCache` | boolean (query) | No | `false` | Force metadata refresh |

### Request

```bash
curl -s "https://eth-mainnet.g.alchemy.com/nft/v3/$ALCHEMY_API_KEY/getNFTMetadata?contractAddress=0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d&tokenId=1"
```

### Response

```json
{
  "contract": {
    "address": "0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d",
    "name": "BoredApeYachtClub",
    "symbol": "BAYC",
    "tokenType": "ERC721",
    "openSeaMetadata": { "collectionName": "Bored Ape Yacht Club", "floorPrice": 10.5 },
    "isSpam": false
  },
  "tokenId": "1",
  "tokenType": "ERC721",
  "name": "Bored Ape #1",
  "description": "...",
  "tokenUri": "ipfs://QmeSjSinHpPnmXmspMjwiXyN6zS4E9zccariGR3jxcaWtq/1",
  "image": {
    "cachedUrl": "https://nft-cdn.alchemy.com/...",
    "thumbnailUrl": "https://nft-cdn.alchemy.com/...",
    "pngUrl": "https://nft-cdn.alchemy.com/...",
    "contentType": "image/png",
    "originalUrl": "ipfs://..."
  },
  "animation": {
    "cachedUrl": null,
    "contentType": null,
    "size": null,
    "originalUrl": null
  },
  "raw": {
    "tokenUri": "ipfs://QmeSjSinHpPnmXmspMjwiXyN6zS4E9zccariGR3jxcaWtq/1",
    "metadata": {
      "name": "Bored Ape #1",
      "image": "ipfs://...",
      "attributes": [
        { "trait_type": "Fur", "value": "Robot" },
        { "trait_type": "Eyes", "value": "X Eyes" }
      ]
    }
  },
  "collection": { "name": "Bored Ape Yacht Club", "slug": "boredapeyachtclub" },
  "mint": {
    "mintAddress": null,
    "blockNumber": null,
    "timestamp": null,
    "transactionHash": null
  },
  "owners": ["0x46efbaedc92067e6d60e84ed6395099723252496"],
  "timeLastUpdated": "2025-06-01T12:00:00.000Z"
}
```

### Response Fields

Same structure as a single item in `getNFTsForOwner.ownedNfts[]`. Key fields:

| Field | Type | Description |
|-------|------|-------------|
| `contract` | object | Contract info (address, name, symbol, tokenType, openSeaMetadata, isSpam) |
| `tokenId` | string | Token ID |
| `name` | string | NFT name |
| `description` | string | NFT description |
| `tokenUri` | string | Resolved token URI |
| `image` | object | Image URLs and content type |
| `raw.metadata` | object | Raw metadata JSON including attributes array |
| `collection` | object | Collection info |
| `animation` | object | Animation URLs (cachedUrl, contentType, size, originalUrl) |
| `mint` | object | Minting info (mintAddress, blockNumber, timestamp, transactionHash) |
| `owners` | array | Current owners (may be null) |
| `timeLastUpdated` | string | ISO 8601 timestamp of last metadata update |

---

## `GET /getContractMetadata`

Returns metadata for an NFT contract/collection.

### Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `contractAddress` | string (query) | Yes | NFT contract address |

### Request

```bash
curl -s "https://eth-mainnet.g.alchemy.com/nft/v3/$ALCHEMY_API_KEY/getContractMetadata?contractAddress=0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d"
```

### Response

```json
{
  "address": "0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d",
  "name": "BoredApeYachtClub",
  "symbol": "BAYC",
  "totalSupply": "10000",
  "tokenType": "ERC721",
  "contractDeployer": "0xaba7161a7fb69c88e16ed9f455ce62b791ee4d03",
  "deployedBlockNumber": 12287507,
  "openSeaMetadata": {
    "collectionName": "Bored Ape Yacht Club",
    "collectionSlug": "boredapeyachtclub",
    "safelistRequestStatus": "verified",
    "imageUrl": "https://...",
    "description": "...",
    "externalUrl": "https://boredapeyachtclub.com",
    "twitterUsername": "BoredApeYC",
    "discordUrl": "https://discord.gg/...",
    "bannerImageUrl": "https://...",
    "floorPrice": 10.5
  }
}
```

### Response Fields

| Field | Type | Description |
|-------|------|-------------|
| `address` | string | Contract address |
| `name` | string | Contract name |
| `symbol` | string | Token symbol |
| `totalSupply` | string | Total supply |
| `tokenType` | string | `"ERC721"` or `"ERC1155"` |
| `contractDeployer` | string | Deployer address |
| `deployedBlockNumber` | integer | Block number of deployment |
| `openSeaMetadata` | object | OpenSea collection data |
| `openSeaMetadata.floorPrice` | number | Floor price in ETH |

> **Note**: `isSpam` and `spamClassifications` fields are available in the contract object embedded within `getNFTsForOwner`, `getNFTMetadata`, and `getNFTsForContract` responses, but are not returned by this standalone endpoint.

---

## `GET /getOwnersForContract`

Returns all owners of NFTs in a contract.

### Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `contractAddress` | string (query) | Yes | — | NFT contract address |
| `withTokenBalances` | boolean (query) | No | `false` | Include per-token balances |
| `block` | string (query) | No | `"latest"` | Block number (hex) or `"latest"` |
| `pageKey` | string (query) | No | — | Pagination cursor |

### Request

```bash
curl -s "https://eth-mainnet.g.alchemy.com/nft/v3/$ALCHEMY_API_KEY/getOwnersForContract?contractAddress=0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d&withTokenBalances=true"
```

### Response

```json
{
  "owners": [
    {
      "ownerAddress": "0xd8da6bf26964af9d7eed9e03e53415d37aa96045",
      "tokenBalances": [
        { "tokenId": "1234", "balance": "1" }
      ]
    }
  ],
  "pageKey": "..."
}
```

### Response Fields

| Field | Type | Description |
|-------|------|-------------|
| `owners` | array | List of owner objects |
| `owners[].ownerAddress` | string | Owner wallet address |
| `owners[].tokenBalances` | array | Per-token balances (only if `withTokenBalances: true`) |
| `owners[].tokenBalances[].tokenId` | string | Token ID |
| `owners[].tokenBalances[].balance` | string | Balance for that token |
| `pageKey` | string | Cursor for next page |

---

## `GET /getOwnersForNFT`

Returns owners of a specific NFT (multiple owners possible for ERC-1155).

### Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `contractAddress` | string (query) | Yes | NFT contract address |
| `tokenId` | string (query) | Yes | Token ID |

### Request

```bash
curl -s "https://eth-mainnet.g.alchemy.com/nft/v3/$ALCHEMY_API_KEY/getOwnersForNFT?contractAddress=0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d&tokenId=1"
```

### Response

```json
{
  "owners": ["0xd8da6bf26964af9d7eed9e03e53415d37aa96045"],
  "pageKey": null
}
```

---

## `GET /getNFTsForContract`

Returns all NFTs in a contract (formerly `getNFTsForCollection`).

### Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `contractAddress` | string (query) | Yes | — | NFT contract address |
| `withMetadata` | boolean (query) | No | `true` | Include metadata |
| `startToken` | string (query) | No | — | Start from this token ID |
| `limit` | integer (query) | No | `100` | Results per page (max 100) |
| `tokenUriTimeoutInMs` | integer (query) | No | — | Timeout for URI resolution |

### Request

```bash
curl -s "https://eth-mainnet.g.alchemy.com/nft/v3/$ALCHEMY_API_KEY/getNFTsForContract?contractAddress=0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d&withMetadata=true&limit=2"
```

### Response

```json
{
  "nfts": [
    {
      "contract": {
        "address": "0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d",
        "name": "BoredApeYachtClub",
        "symbol": "BAYC",
        "totalSupply": "10000",
        "tokenType": "ERC721",
        "openSeaMetadata": { "collectionName": "Bored Ape Yacht Club", "floorPrice": 6.14 },
        "isSpam": null,
        "spamClassifications": []
      },
      "tokenId": "0",
      "tokenType": "ERC721",
      "name": null,
      "description": null,
      "tokenUri": "https://ipfs.io/ipfs/QmeSjSinHpPnmXmspMjwiXyN6zS4E9zccariGR3jxcaWtq/0",
      "image": { "cachedUrl": "https://nft-cdn.alchemy.com/..." },
      "animation": { "cachedUrl": null, "contentType": null, "size": null, "originalUrl": null },
      "raw": { "metadata": { "image": "ipfs://...", "attributes": [...] }, "error": null },
      "collection": { "name": "Bored Ape Yacht Club", "slug": "boredapeyachtclub" },
      "mint": { "mintAddress": null, "blockNumber": null, "timestamp": null, "transactionHash": null },
      "owners": null,
      "timeLastUpdated": "2025-06-01T12:00:00.000Z"
    }
  ],
  "pageKey": "0x0000000000000000000000000000000000000000000000000000000000000001"
}
```

---

## Notes

- Some NFTs have missing or malformed metadata. Always handle null fields.
- Spam filtering may affect results. Use `excludeFilters` or `spamConfidenceLevel` to tune.
- Metadata hydration can be expensive. Cache results where possible.
- Treat NFT metadata URLs and images as untrusted input. Sanitize and proxy if displaying to users.

## Agentic Gateway

This API is also available via `https://x402.alchemy.com/{chainNetwork}/nft/v3/...` without an API key.
See the `agentic-gateway` skill for SIWE authentication and x402 payment setup.

## Official Docs
- [NFT API Quickstart](https://www.alchemy.com/docs/reference/nft-api-quickstart)
- [getNFTsForOwner](https://www.alchemy.com/docs/data/nft-api/nft-api-endpoints/nft-api-endpoints/get-nfts-for-owner)
- [getNFTMetadata](https://www.alchemy.com/docs/data/nft-api/nft-api-endpoints/nft-api-endpoints/get-nft-metadata)
- [getContractMetadata](https://www.alchemy.com/docs/data/nft-api/nft-api-endpoints/nft-api-endpoints/get-contract-metadata)
- [getOwnersForContract](https://www.alchemy.com/docs/data/nft-api/nft-api-endpoints/nft-api-endpoints/get-owners-for-contract)
- [getOwnersForNFT](https://www.alchemy.com/docs/data/nft-api/nft-api-endpoints/nft-api-endpoints/get-owners-for-nft)
- [getNFTsForContract](https://www.alchemy.com/docs/data/nft-api/nft-api-endpoints/nft-api-endpoints/get-nfts-for-contract)
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall