When money or an NFT is stuck

Four things in this addon can leave a customer holding neither their money nor their NFT, and none of them resolve on their own. Each has a specific row, a specific flag, and — in three of the four cases — a door that is not where you would expect it to be.

Work the symptom, not the cause. The one at the top is the most common blocker on a new install and it is not a bug.

"Connect a wallet address in your profile"

This is a 400, not a permissions problem, and it means exactly what it says: the account has no user.walletAddress.

The message is assembled in nft/utils/nft-auth.ts as "Connect a wallet address in your profile to <action>", so the trailing words tell you which door was refused:

Three more doors refuse for the same reason with their own wording:

• POST /api/nft/bid — two separate refusals. "Connect a wallet address in your profile to place bids with transaction verification" fires whenever the request carries a transactionHash. "Connect a wallet address in your profile to bid on an on-chain auction" fires when the listing has an auctionContractAddress, because the bid is sent to that contract from a real address. A database-only auction with no hash takes the bid without either.
• POST /api/nft/offer/{id}/confirm — "Cannot verify transfer: both the buyer and the seller must have a wallet address set in their profile". Both sides. One missing address here is what sends an accepted offer into the 24-hour unwind.
• POST /api/nft/auction/deploy — "Seller must have wallet address set".
• POST /api/nft/auction/{id}/settle — "No valid winning bid found or winner missing wallet address" and "Seller wallet address not found". A winner who unlinked their wallet after bidding stalls the settlement here.

The fix is on the customer's own profile

The column is a read-only mirror. It is written by exactly one thing: the SIWE wallet-link flow at /user/profile?tab=wallet, where the customer connects a wallet and signs a message. That writes a provider_user row with provider = 'WALLET', and an afterSave hook on that model copies the address into user.walletAddress.

One address per account: linking an address that already belongs to a different account returns 409 "This wallet address is already linked to a different account."

Blocked auction settlement

Row: nft_listing.settlementBlockedAt is not null and status is still ACTIVE.

Where you see it: the Blocked settlements tile in the Decision queue on /admin/nft, which links to Admin → NFT → Trading → Auctions (/admin/nft/auction). Affected rows carry a red Settlement blocked badge, and the view dialog shows Settlement blocked at under Timeline → Settlement. The same badge appears on /admin/nft/listing.

What it means

The settleAuctions cron stamps this when an auction ends with a winning bid but the listing has no auctionContractAddress (or the collection has no chain). Auction escrow lives inside the per-listing NFTAuction contract — bid sends the money to it, endAuction pays the seller out of it. With no contract, no money was ever escrowed anywhere.

So the good news first: nobody has been charged and nobody is owed a refund. The bids are database rows. What is stuck is the token — it is off the market with a nominal winner and nothing that can pay the seller.

The flag also stops the cron re-selecting the same unsettleable rows every ten minutes, which used to fill the batch window and starve auctions that could settle.

What clears the flag, and why it is not an admin action

Exactly one thing writes settlementBlockedAt back to NULL: POST /api/nft/auction/deploy. That route checks listing.sellerId === user.id and enforces the sell_nft KYC feature — it is the seller's screen (/nft/token/{id}/list), not an admin one. No admin route, and no control on the admin console, clears the flag.

The safe recovery

The seller cannot do step 2 themselves. DELETE /api/nft/listing/{id} returns 409 "Cannot cancel auction with active bids. Contact support if needed." That message is pointing at you.

Why you should see few new ones

Two guards were added after this failure mode was found. POST /api/nft/listing now refuses an auction whose collection contract is not deployed or whose token has no blockchainTokenId, and the seller's listing screen calls /api/nft/auction/deploy immediately after creating the listing, deleting the listing again if the deployment fails. Blocked rows on a current install are almost always legacy.

Flagged escrow

Row: nft_offer.flaggedAt is not null on an offer whose status is still ACCEPTED.

Where you see it: the Flagged escrow tile in the Decision queue on /admin/nft, linking to Admin → NFT → Trading → Offers (/admin/nft/offer). The row carries a red Flagged badge and a Flagged for review entry in its timeline.

What it means

An accepted offer whose on-chain transfer is never confirmed is unwound after nftTransferConfirmGraceHours (default 24) by the expireOffers cron. Normally that just releases the buyer's hold and puts the token back on the market.

flaggedAt is written when the release itself fails with InsufficientHeldFundsError — the buyer's wallet.inOrder is smaller than what the hold ledger says was reserved. Placing the hold moved that money out of wallet.balance, so the buyer really is short by that amount and really has no NFT.

The sweep also:

• creates an nft_dispute row with disputeType = 'NOT_RECEIVED', status = 'PENDING', priority = 'HIGH', the buyer as reporterId and the seller as respondentId;
• notifies every admin holding access.nft.dispute, linking to /admin/nft/dispute;
• stamps flaggedAt so the sweep stops re-processing and re-notifying the same offer every five minutes forever.

Establish the amount from the hold row, never from the fee

The escrow was sized when the offer was made, as amount + marketplace fee at that moment. The wallet service wrote it as a transaction row under a stable idempotency key. That row is the authority:

SELECT userId, walletId, amount, createdAt
FROM   transaction
WHERE  idempotencyKey = 'nft_offer_hold_<offerId>';

Recomputing from today's nftMarketplaceFeePercentage is wrong whenever the fee changed in between: too high and you hand back other operations' held funds, too low and the residue is stranded forever. Every release path in the product reads this row for exactly that reason.

Resolving it

A flagged escrow means the wallet ledger disagreed with itself, which does not happen on its own. Treat it as a signal to check that account's other holds before you close the ticket.

Emergency pause answers "Marketplace contract not found"

POST /api/nft/marketplace/pause looks up the platform setting nft_marketplace_address_<chain> — lower-cased chain — and returns 404 unless it exists and equals the address you sent. Unpause, config, whitelist and withdraw all do the same lookup.

Nothing writes that key. POST /api/nft/marketplace/deploy records the contract in the nft_marketplace table and never touches settings. On any install where nobody wrote it by hand, the emergency controls are dead in an emergency.

Write it before you need it. It is not on any settings form, but the generic settings endpoint will create it:

Send {"nft_marketplace_address_eth": "0x…"} for each chain you have deployed to. New keys are allowed as long as the name matches [A-Za-z0-9_][A-Za-z0-9_.:-]*, and the endpoint clears the settings cache when it is done.

There is a second caveat that the key does not fix: the shipped NFTMarketplace contract does not implement OpenZeppelin's Pausable, so pausing is a platform-side flag your own screens honour rather than a guarantee the chain will refuse a transaction. Marketplace contracts covers both.

Fees that are not stuck, but are not yours yet

Fees from on-chain sales sit inside the marketplace contract as a native-token balance. There is no alert, no scheduled sweep and no dashboard tile for it. The only place it is visible is the per-chain card at the top of Admin → NFT → Trading → Marketplace (/admin/nft/marketplace) and the available-balance line on its Revenue Withdrawal tab.

Withdraw with POST /api/nft/marketplace/withdraw — chain, contractAddress and a reason are required; omit amount to take everything and omit withdrawalAddress to send to the contract's configured fee recipient.

Set yourself a recurring reminder. See Marketplace contracts and Fees and royalties.

What is not stuck

• An ACCEPTED offer inside the grace window. It is waiting for POST /api/nft/offer/{id}/confirm from either party. The sweep will deal with it after nftTransferConfirmGraceHours.

• An EXPIRED offer. Both the expiry job and the stale sweep release the hold before they write that status.

• A SOLD auction with no ledger rows. The seller-payment and buyer-transfer transaction rows written at auction settlement are informational mirrors of an on-chain payment; the settlement does not abort if they fail. Check the chain, not the wallet.

• A database-only auction that ended below its reserve. It becomes EXPIRED, every bid is REJECTED, and no money was ever held.

  This is only safe while the listing has no auctionContractAddress, and that is no longer the common case — the seller's listing screen deploys an auction contract immediately. Once one exists, POST /api/nft/bid sends every bid on chain with auctionContract.bid({ value: … }), so the money really is sitting inside the NFTAuction contract. The reserve-not-met branch of settleAuctions writes EXPIRED, isListed: false and REJECTED bids and never touches the contract — it does not call endAuction and it issues no refund. The contract does expose pendingReturns, withdraw and emergencyWithdraw, but nothing in the product calls them for you: auction-service.ts has a withdrawFunds helper that no route and no cron invokes. An on-chain auction that fails its reserve is stuck, and clearing it is an on-chain job, not an admin-console one.

If the cron process is not running, none of the above happens at all: offers never expire, auctions never settle, and nothing is flagged. Check the admin cron screen for expireOffers (every 5 minutes) and settleAuctions (every 10 minutes) before you investigate a single row.

Related

• Troubleshooting — minting, images, menus and permissions.
• Listings, sales, auctions and offers — the mechanics behind each state above.
• Settings — nftTransferConfirmGraceHours and the rest.
• Marketplace contracts — pause, config and withdrawal.
• Permissions — edit.nft, edit.nft.dispute, access.nft.dispute.