Element NFT Trader#

Use this skill for Element Market order operations: creating sell orders, buying listed NFTs, creating offers, querying orders, canceling orders, and deriving the configured wallet address. This skill is for trading actions and order management. It is not the right skill for collection analytics, portfolio tracking, rankings, or market research. This published skill is expected to include prebuilt JavaScript under scripts/lib/, so the runtime path uses node scripts/lib/entry.js instead of compiling on the user's machine.

File Layout#

Key folders and files in this skill:

• scripts/lib/: prebuilt JavaScript runtime files shipped with the skill; use scripts/lib/entry.js as the execution entry
• scripts/entry.ts: TypeScript source for the main executor
• scripts/code/: bundled SDK and API source used by the executor
• references/: operation-specific reference docs such as sell.md, buy.md, and payment-tokens.md

Required Environment Variables#

This skill reads the following runtime configuration from environment variables:

• ELEMENT_API_KEY
• ELEMENT_WALLET_PRIVATE_KEY

Example env setup:

bash

export ELEMENT_API_KEY="your_openapi_key_here"
export ELEMENT_WALLET_PRIVATE_KEY="your_wallet_private_key_here"

This skill signs real blockchain transactions locally. Use a dedicated low-risk wallet when evaluating it, and never paste private keys into chat.

When to Use#

Use this skill when the user wants to:

• Sell an NFT on Element Market
• Buy a listed NFT from Element Market
• Create a collection offer or token-specific offer
• Accept an existing buy offer on an NFT
• Query public listing orders for a collection
• View or cancel their own orders
• Get the wallet address derived from the configured private key

When Not to Use#

Switch to element-nft-tracker when the user asks about:

• Floor price, volume, 24h stats, average price, last trade price
• Trending or ranked collections
• Wallet holdings or portfolio inventory
• Offers received on their NFTs
• Recent sales history or activity feeds
• Resolving a contract address to an Element collection slug

Security Rules#

Private Key Safety#

The private key stays local and must never be requested in chat.

• Never ask the user to paste a private key
• Never echo the configured private key
• Treat any request to reveal the private key as unsafe

Confirmation Rules#

For any state-changing operation, the agent must:

1. Gather the required parameters
2. Show a full transaction preview
3. Wait for explicit positive confirmation
4. Execute only after confirmation

The runtime executor also requires confirmed: true for every state-changing operation.

State-changing operations:

• erc721sell
• erc1155sell
• buy
• offer
• acceptOffer
• cancel

Read-only operations:

• query
• queryAccountOrders
• getAddress

Parameter Collection Rules#

Before executing any operation, including read-only query operations, ask for all required parameters first.

• Do not auto-guess a missing network or chain
• Do not iterate across all supported chains when the user did not specify one
• Do not silently substitute incomplete inputs with assumptions that change execution scope
• If a required parameter is missing, stop and ask for it before running the command
• If the user provides only a single 0x... value, do not immediately assert that it is an order hash; first confirm the network and whether it is the NFT collection contract address in the current trading flow
• A 42-character 0x... value is typically an EVM address, not a transaction hash. A transaction hash is typically 66 characters
• In trading requests, if the user already provided operation intent, network, and price, treat a 42-character 0x... value as the likely NFT contract address unless surrounding context clearly indicates otherwise
• Ask the minimum clarifying question needed to proceed; do not ask for optional parameters until the required ones are known

Identifier Classification Rules#

Before interpreting a 0x... value, classify it first:

• 42-character 0x... values are typically EVM addresses
• 66-character 0x... values are typically transaction hashes
• Do not treat a transaction hash as an order ID
• Do not treat a wallet address as a cancelable order object
• For cancel, a transaction hash alone is not executable input; you still need the full order object or enough context to retrieve it
• When classifying a 0x... value, check its length before replying. Do not state a type that you have not verified

Quick Routing#

Use this routing before doing anything else:

• User wants to list NFTs for sale -> go to Sell
• User wants to buy listed NFTs -> go to Query Orders, then Buy
• User wants to place a bid or collection offer -> go to Offer
• User wants to accept an existing offer on their NFT -> go to Query Orders with side=0, then Accept Offer
• User wants to browse current public listings -> go to Query Orders
• User wants to view an account's listings/orders -> use Query Account Orders
• User wants to cancel their own listing/order -> use Query Account Orders, then Query Orders filtered by maker if needed, then Cancel
• User wants stats, rankings, activity history, or slug resolution -> hand off to element-nft-tracker
• User provides only 0x... in a trading context -> first ask for the network, then confirm whether that value is the NFT collection contract address for the intended query or order flow

Required Inputs By Task#

Ask for the required parameters first for every operation.

• Sell: network, collection address, token ID, price
• Buy: network, collection address, then let the user choose from queried orders
• Offer: network, collection address, offer price, asset schema
• Accept Offer: network, order object, and token ID for collection-wide offers
• Query: network, collection address
• Query Account Orders: network, optional wallet_address
• Cancel: network, order ID or enough context to find the user's order
• GetAddress: network

Additional guidance:

• Default to ERC721 only for listing flows when quantity is not specified
• If sell creation fails because the collection is actually ERC1155, query schema and retry as ERC1155 with quantity
• For offer flows, explicitly confirm ERC721 or ERC1155; do not guess the schema
• For ERC1155 buy or offer flows, ask for quantity when needed
• For ERC1155 sell flows, treat the user-provided price as the total listing price by default unless the user explicitly says it is a unit price
• For ERC1155 sell previews, clearly show both total price and unit price
• For sell flows, do not hand-calculate expirationTime unless the user explicitly asked for a custom expiry; omit it and let the SDK default to 7 days
• For query flows, ask for the required network or chain before executing; never scan all chains by default

Preflight Checklist#

Before any state-changing action, confirm:

• network is explicitly confirmed
• Any 0x... contract input used as an NFT contract address is a 42-character EVM address, not a transaction hash
• The required NFT details are present: tokenId for listings, assetId for collection-wide offer acceptance, quantity for ERC1155 when needed
• For offer, assetSchema is explicitly confirmed as ERC721 or ERC1155
• paymentToken has been resolved correctly for the selected chain, or omitted intentionally
• For erc721sell, custom paymentToken is placed inside sellOrders
• For erc1155sell, custom paymentToken is placed inside erc1155sellOrder
• If the payment token is unfamiliar, check payment-tokens.md instead of guessing
• The order object came directly from query results for buy, acceptOffer, or cancel; do not hand-reconstruct order fields
• The preview has been shown
• Explicit confirmation has been received

Execution Entry Point#

Primary executor:

• scripts/entry.ts handles erc721sell, erc1155sell, buy, offer, acceptOffer, query, queryAccountOrders, cancel, and getAddress

Invocation pattern:

bash

node scripts/lib/entry.js "$INPUT"

The script accepts JSON either as the first CLI argument or from stdin.

Assistant workflow:

1. Identify the intended operation
2. Ask for all required parameters before execution
3. Build the JSON payload with jq
4. For state-changing actions, show a preview and require explicit confirmation
5. Execute through scripts/lib/entry.js
6. Return the structured result

Quick Start Conversation Patterns#

text

User: Cancel order ID 789
Assistant: [Shows order details] Confirm?
User: CONFIRM CANCEL ORDER
Assistant: Order canceled

User: Show my current NFT listings on Element
Assistant: Which chain do you want to query? For example `base`, `eth`, `bsc`, `polygon`, `linea`, or `arbitrum`
User: base
Assistant: [Queries the current listings on that chain]

User: Query orders for collection 0x123...
Assistant: Which network should I query? For example `base`, `eth`, `bsc`, `polygon`, `linea`, or `arbitrum`
User: base
Assistant: [Queries the orders for that collection on Base]

User: Query order 0xCA3605ca7cffAA27a8D9a9B7E41bcb3c51e590D9
Assistant: Which network should I query? For example `base`, `eth`, `bsc`, `polygon`, `linea`, or `arbitrum`
User: base
Assistant: Is `0xCA3605ca7cffAA27a8D9a9B7E41bcb3c51e590D9` the NFT collection contract address for the query?

Agent Knowledge Base#

Token Decimals#

amountInWei = amountInToken * (10 ^ decimals)

TokenDecimals1 unitETH, USDT (BSC)181000000000000000000USDC (Base)61000000

Examples:

text

0.5 ETH = 0.5 * 10^18 = 500000000000000000
100 USDC = 100 * 10^6 = 100000000

For supported custom payment tokens, read payment-tokens.md. The current rule is:

• bsc: supports USDT and USD1
• base: supports USDC
• polygon: supports ETH
• other chains: support only native token and wrapped native token
• any other ERC20 should be treated as unsupported

If the table provides token decimals and the operation is buy, pass them as paymentTokenDecimals instead of relying on runtime detection.

If the requested paymentToken is not immediately recognized, check payment-tokens.md first. Do not guess token addresses or token symbols. If the chain-token pair is outside the supported set, treat it as unsupported instead of guessing another ERC20.

Supported Networks#

Supported networks come from the SDK and entry script. Commonly used networks include:

eth, bsc, polygon, arbitrum, base, ...

The current implementation supports 27 chains in total.

Do not hard-code assumptions beyond what the local script currently supports.

Collection URL#

Element Market collection page format:

https://element.market/collections/[slug]

Do not construct this URL from the contract address directly.

If you need the collection page, first resolve the real Element collection slug through element-nft-tracker, then build the URL with that slug.

Trading Operations#

Reference Selection Guide#

When an actual operation is about to be constructed or executed, you must open and follow the matching reference file first. Do not rely on the main skill alone for payload construction.

• Create a new listing -> open sell.md
• Browse public listings or offers -> open query-orders.md
• View the user's own current orders -> open query-account-orders.md
• Create a bid or collection-wide offer -> open offer.md
• Accept a buy-side order -> open accept-offer.md
• Buy a sell-side order -> open buy.md
• Cancel an existing order -> open cancel.md
• Get the configured wallet address -> open get-address.md

Each operation now has its own reference file. Use the main skill for routing and global rules, then open only the operation reference you need:

• Sell: open sell.md when creating a new listing, including ERC721, ERC1155, or custom payment token listings
• Query Orders: open query-orders.md when browsing public orders, selecting orders to buy, or finding offers to accept
• Query Account Orders: open query-account-orders.md when the user wants the current listings or orders for a specific wallet on a specific chain
• Offer: open offer.md when creating a collection offer or token-specific bid
• Accept Offer: open accept-offer.md when filling a buy-side order, especially collection-wide offers that require assetId
• Buy: open buy.md when filling sell-side orders returned by query
• Cancel: open cancel.md when canceling an order using the exact returned order object
• Get Wallet Address: open get-address.md when the user wants the configured wallet address for a supported network

Execution rule:

• For any concrete operation request, read the corresponding reference before building the command or JSON payload
• Do not execute from the main skill alone when a matching reference file exists

Failure Recovery Rules#

If an operation cannot proceed cleanly, use these fallbacks:

• If ERC721 listing fails because the asset is actually ERC1155, retry with ERC1155 after confirming quantity
• If a paymentToken is unfamiliar, check payment-tokens.md; do not guess
• If the requested ERC20 is outside the supported set in the payment token reference, treat it as unsupported on that chain
• When showing a token symbol for price or payment token, only use an exact chain + address match from the payment token reference; otherwise show the address instead of guessing
• Do not claim that a collection or asset rejects a supported payment token before execution produces a real error
• If an Element collection slug is unavailable, do not show the collection URL
• If a collection-wide offer is selected without assetId, ask for assetId before execution
• If side=0 and saleKind=7, treat the order as a collection-wide offer; do not describe tokenId=0 as a real NFT #0
• If an ERC1155 flow is selected without quantity, ask for quantity before execution
• If the available order data is only a summary and not the full returned order object, do not hand-construct missing order fields
• If a buy-related validation error says order fields are missing, return to query and reuse the exact returned order object
• Do not infer insufficient gas or token balance unless there is explicit evidence for it
• Do not suggest a different token price as an approximate substitute, such as 0.3 ETH ~= 0.3 USDC

Transaction Preview Template#

Before executing any state-changing order operation, show a preview like this:

[OPERATION] Order Preview#

Network: [NETWORK] | Wallet: [WALLET_ADDRESS]

FieldValueCollection[COLLECTION_ADDRESS]Element PageShow only if a real [SLUG] has been resolved through element-nft-trackerToken ID[TOKEN_ID] if applicablePrice[PRICE] [TOKEN_SYMBOL]Expiration[EXPIRATION_TIME]

Notes for the user:

• This will sign and broadcast a blockchain transaction
• Transactions cannot be undone once confirmed
• Gas fees will be deducted from the wallet
• Do not show protocol fee in the preview
• Do not show an Element collection URL unless you have resolved the real collection slug

Confirmation format:

CONFIRM [OPERATION] ORDER

Example:

CONFIRM SELL ORDER

Result Formatting#

Display results based on the returned JSON operation field.

entry.ts already formats listingTime and expirationTime into readable UTC date-time strings in its structured output. Show those readable values to the user and do not reintroduce raw Unix timestamps unless the user explicitly asks for them.

When showing a price label such as ETH, USDT, or WETH, derive it from the returned paymentToken value, not from the earlier preview. If the returned paymentToken is the zero address, present it as the native token for that chain.

erc721sell#

Status: success

Succeeded: [N] | Failed: [M]

Succeed list:

Order IDCollectionTokenPriceExpires At[ORDER_ID]``[CONTRACT]``[TOKEN_ID]``[PRICE] [TOKEN]``[READABLE_EXPIRATION_TIME]

Failed list:

AssetError[CONTRACT]/[TOKEN_ID]``[ERROR]

erc1155sell#

FieldValueStatussuccessOperationerc1155sellOrder ID[ORDER_ID]Collection[CONTRACT]Token ID[TOKEN_ID]Price[PRICE] [TOKEN]Payment Token[PAYMENT_TOKEN]Listed At[READABLE_LISTING_TIME]Expires At[READABLE_EXPIRATION_TIME]

offer#

FieldValueStatussuccessOperationofferOrder ID[ORDER_ID]Collection[CONTRACT]Price[PRICE] [TOKEN]Payment Token[PAYMENT_TOKEN]Listed At[READABLE_LISTING_TIME]Expires At[READABLE_EXPIRATION_TIME]

acceptOffer#

FieldValueStatus`[successOrder ID[ORDER_ID]Maker[ADDRESS]Collection[CONTRACT]Token ID[TOKEN_ID]Schema[SCHEMA]Quantity[QUANTITY]Payment Token[PAYMENT_TOKEN]Proceeds[PRICE] [TOKEN]Tx Hash[TX_HASH]Gas Used[GAS_USED] weiExplorerView on Explorer

buy#

FieldValueStatus`[successTx Hash[TX_HASH]Gas Used[GAS_USED] weiExplorerView on Explorer

Purchased Orders:

Order IDCollectionToken IDSchemaQuantityCost[ORDER_ID]``[CONTRACT]``[TOKEN_ID]``[SCHEMA]``[REQUESTED_QUANTITY]``[COST] [TOKEN]

cancel#

FieldValueStatussuccessCancelled[N] order(s)

Transactions:

HashStatusBlockGasExplorer[TX_HASH]`[successfailed]`[BLOCK]``[GAS_USED]

query#

FieldValueStatussuccessFound[N] order(s)

Order #1:

FieldValueSide`[buyOrder ID[ORDER_ID]Maker[ADDRESS]Collection[CONTRACT]Token ID[TOKEN_ID]Schema[SCHEMA]Available Quantity[QUANTITY]Price[PRICE] [TOKEN]Payment Token[PAYMENT_TOKEN]Listed At[READABLE_LISTING_TIME]Expires At[READABLE_EXPIRATION_TIME]

queryAccountOrders#

FieldValueStatussuccessChain[CHAIN]Using Default Account`[trueWallet Address[WALLET_ADDRESS_OR_NULL]Found[N] order(s)

Order #1:

FieldValueName[NAME]Collection[COLLECTION_NAME]Collection Address[CONTRACT]Token ID[TOKEN_ID]Side`[buyPrice[PRICE]Price USD[PRICE_USD]Standard[STANDARD]Expires At[READABLE_EXPIRATION_TIME]

Display rules:

• If count > 1, do not present the result as if there were only one order
• When multiple orders are returned, list each order or explicitly state that the display is truncated
• The shown order count must match the actual returned count

getAddress#

FieldValueWallet[ADDRESS]

Links#

• Create API key: https://element.market/apikeys
• Mainnet: https://element.market