{"ok":true,"site":{"host":"artsoulprotocol.com","url":"https://artsoulprotocol.com/docs-protocol","type":"live","desc":"User documentation for ArtSoul discovery-first auctions, deposit-backed bidding, settlement, lazy minting, fees, trust, and provenance.","tools":[{"name":"search_artworks","kind":"answer","impl":"imperative","description":"Search published ArtSoul artworks on Base Sepolia by free text, artwork number, creator or lifecycle status. Answers come from ArtSoul's own indexer, which reconstructs state from confirmed Base events and is the source the site itself renders, so no separate contract read is needed. Read-only.","inputSchema":{"type":"object","properties":{"query":{"type":"string","description":"Free text matched against title, description and creator."},"creator":{"type":"string","description":"Creator wallet address or public nickname."},"status":{"type":"string","enum":["any","auction","for_sale"],"description":"Restrict to works with a live auction, works listed for resale, or any work."},"limit":{"type":"integer","minimum":1,"maximum":20}}},"hasHandler":true,"hasExecute":true,"__source":"spec","executable":true,"handlerField":"execute","page":"/docs-protocol","pages":["/docs-protocol","/","/profile","/gallery","/upload"]},{"name":"find_active_auctions","kind":"answer","impl":"imperative","description":"List ArtSoul auctions that are open for bidding right now, soonest ending first. Use this before discussing a bid so the deadline is current. Read-only.","inputSchema":{"type":"object","properties":{"ending_within_hours":{"type":"number","minimum":0,"description":"Only auctions ending within this many hours."},"limit":{"type":"integer","minimum":1,"maximum":20}}},"hasHandler":true,"hasExecute":true,"__source":"spec","executable":true,"handlerField":"execute","page":"/docs-protocol","pages":["/docs-protocol","/","/profile","/gallery","/upload"]},{"name":"get_artwork","kind":"answer","impl":"imperative","description":"Full public detail of one ArtSoul artwork on Base Sepolia: title, description, creator, owner, lifecycle status, prices, auction timing and community signals. Read-only.","inputSchema":{"type":"object","properties":{"artwork_id":{"type":"string","description":"The artwork number shown in its page URL."}},"required":["artwork_id"]},"hasHandler":true,"hasExecute":true,"__source":"spec","executable":true,"handlerField":"execute","page":"/docs-protocol","pages":["/docs-protocol","/","/profile","/gallery","/upload"]},{"name":"get_auction_state","kind":"answer","impl":"imperative","description":"Return the live state of one ArtSoul auction: status, current bid, current bidder, bid history, end time and settlement deadline. Read-only.","inputSchema":{"type":"object","properties":{"artwork_id":{"type":"string","description":"The artwork number shown in its page URL."}},"required":["artwork_id"]},"hasHandler":true,"hasExecute":true,"__source":"spec","executable":true,"handlerField":"execute","page":"/docs-protocol","pages":["/docs-protocol","/","/profile","/gallery","/upload"]},{"name":"get_artwork_provenance","kind":"answer","impl":"imperative","description":"Return ArtSoul provenance for one artwork: Creator, First Collector and current Owner, plus the event timeline rebuilt from indexed Base events. Read-only.","inputSchema":{"type":"object","properties":{"artwork_id":{"type":"string","description":"The artwork number shown in its page URL."}},"required":["artwork_id"]},"hasHandler":true,"hasExecute":true,"__source":"spec","executable":true,"handlerField":"execute","page":"/docs-protocol","pages":["/docs-protocol","/","/profile","/gallery","/upload"]},{"name":"explain_settlement","kind":"answer","impl":"imperative","description":"Explain the ArtSoul lifecycle - publish, auction, settlement, lazy mint, floor - and, when an artwork is named, where that specific work currently sits in it. Read-only.","inputSchema":{"type":"object","properties":{"artwork_id":{"type":"string","description":"Optional artwork number to place in the lifecycle."}}},"hasHandler":true,"hasExecute":true,"__source":"spec","executable":true,"handlerField":"execute","page":"/docs-protocol","pages":["/docs-protocol","/","/profile","/gallery","/upload"]},{"name":"get_my_activity","kind":"answer","impl":"imperative","description":"What the connected wallet has on ArtSoul: works it created, NFTs it owns, auctions it is leading, settlements it has won and must pay with their deadlines, its resale listings, funds waiting to be withdrawn, and the next actions that need it, each naming the tool that performs it. Read-only.","inputSchema":{"type":"object","properties":{}},"hasHandler":true,"hasExecute":true,"__source":"spec","executable":true,"handlerField":"execute","page":"/docs-protocol","pages":["/docs-protocol","/","/profile","/gallery","/upload"]},{"name":"open_artwork","kind":"act","impl":"imperative","description":"Open an ArtSoul artwork page in the browser so the person can see it. Navigates only; it changes nothing and signs nothing.","inputSchema":{"type":"object","properties":{"artwork_id":{"type":"string","description":"The artwork number shown in its page URL."}},"required":["artwork_id"]},"hasHandler":true,"hasExecute":true,"__source":"spec","executable":true,"handlerField":"execute","page":"/docs-protocol","pages":["/docs-protocol","/","/profile","/gallery","/upload"]},{"name":"prepare_bid","kind":"act","impl":"imperative","description":"Prepare a bid on an ArtSoul auction: report the live state, open the auction page and hand the action to the person. This tool CANNOT place or sign a bid - the person reviews the amount and signs it in their own wallet.","inputSchema":{"type":"object","properties":{"artwork_id":{"type":"string","description":"The artwork number shown in its page URL."},"intended_bid_eth":{"type":"string","description":"Optional amount in ETH the person is considering, for context only."}},"required":["artwork_id"]},"hasHandler":true,"hasExecute":true,"__source":"spec","executable":true,"handlerField":"execute","page":"/docs-protocol","pages":["/docs-protocol","/","/profile","/gallery","/upload"]},{"name":"place_bid","kind":"act","impl":"imperative","description":"Open the connected wallet with a bid on an ArtSoul auction, so the person can review and approve it. Requires a connected wallet and a permission the person grants in the page. The agent does not sign: the wallet asks the person to confirm, and the transaction only exists once they do.","inputSchema":{"type":"object","properties":{"artwork_id":{"type":"string","description":"The artwork number shown in its page URL."},"bid_eth":{"type":"string","description":"The bid amount in ETH the person wants to offer."}},"required":["artwork_id","bid_eth"]},"hasHandler":true,"hasExecute":true,"__source":"spec","executable":true,"handlerField":"execute","page":"/docs-protocol","pages":["/docs-protocol","/","/profile","/gallery","/upload"]},{"name":"end_expired_auction","kind":"act","impl":"imperative","description":"Finalize an ArtSoul auction whose end time has passed, by opening the wallet so the person can approve the transaction. Anyone may finalize an expired auction; the caller receives nothing and pays only gas. Requires a connected wallet and the same permission as place_bid.","inputSchema":{"type":"object","properties":{"artwork_id":{"type":"string","description":"The artwork number shown in its page URL."}},"required":["artwork_id"]},"hasHandler":true,"hasExecute":true,"__source":"spec","executable":true,"handlerField":"execute","page":"/docs-protocol","pages":["/docs-protocol","/","/profile","/gallery","/upload"]},{"name":"complete_settlement","kind":"transact","impl":"imperative","description":"Pay for an ArtSoul auction the connected wallet won, which mints the NFT to that wallet. Opens the wallet with the remaining payment the contract computes. Only the winner can settle, and only while the settlement window is open. Confirmed by the person on the page and in their wallet.","inputSchema":{"type":"object","properties":{"artwork_id":{"type":"string","description":"The artwork number shown in its page URL."}},"required":["artwork_id"]},"hasHandler":true,"hasExecute":true,"__source":"spec","executable":true,"handlerField":"execute","page":"/docs-protocol","pages":["/docs-protocol","/","/profile","/gallery","/upload"]},{"name":"close_expired_settlement","kind":"act","impl":"imperative","description":"Close an ArtSoul settlement whose payment window has passed without payment, recording the default on-chain so the creator can auction the work again. Anyone may do this; the caller receives nothing and pays only gas. Requires a connected wallet and the agent wallet permission.","inputSchema":{"type":"object","properties":{"artwork_id":{"type":"string","description":"The artwork number shown in its page URL."}},"required":["artwork_id"]},"hasHandler":true,"hasExecute":true,"__source":"spec","executable":true,"handlerField":"execute","page":"/docs-protocol","pages":["/docs-protocol","/","/profile","/gallery","/upload"]},{"name":"start_auction","kind":"act","impl":"imperative","description":"Start a primary auction for an unminted ArtSoul work the connected wallet created, with a starting price in ETH and a duration in hours. The contract accepts only its fixed durations, and this tool reads them from the chain. Confirmed by the person on the page and in their wallet.","inputSchema":{"type":"object","properties":{"artwork_id":{"type":"string","description":"The artwork number shown in its page URL."},"start_price_eth":{"type":"string","description":"The starting price in ETH."},"duration_hours":{"type":"number","description":"Auction length in hours, one the contract accepts."}},"required":["artwork_id","start_price_eth","duration_hours"]},"hasHandler":true,"hasExecute":true,"__source":"spec","executable":true,"handlerField":"execute","page":"/docs-protocol","pages":["/docs-protocol","/","/profile","/gallery","/upload"]},{"name":"list_for_resale","kind":"answer","impl":"imperative","description":"List an ArtSoul NFT the connected wallet owns for resale at a price in ETH, at or above its canonical floor. The wallet may ask twice: once to let ArtSoul transfer the NFT when it sells, once for the listing. Confirmed by the person on the page and in their wallet.","inputSchema":{"type":"object","properties":{"artwork_id":{"type":"string","description":"The artwork number shown in its page URL."},"price_eth":{"type":"string","description":"The asking price in ETH."}},"required":["artwork_id","price_eth"]},"hasHandler":true,"hasExecute":true,"__source":"spec","executable":true,"handlerField":"execute","page":"/docs-protocol","pages":["/docs-protocol","/","/profile","/gallery","/upload"]},{"name":"buy_resale_listing","kind":"transact","impl":"imperative","description":"Buy an ArtSoul NFT listed for resale, at the price the contract holds for the listing right now. Pass the price the person agreed to as expected_price_eth, and the purchase is refused if the listing has changed since. Confirmed by the person on the page and in their wallet.","inputSchema":{"type":"object","properties":{"artwork_id":{"type":"string","description":"The artwork number shown in its page URL."},"expected_price_eth":{"type":"string","description":"The price in ETH the person agreed to. A different live price stops the purchase."}},"required":["artwork_id"]},"hasHandler":true,"hasExecute":true,"__source":"spec","executable":true,"handlerField":"execute","page":"/docs-protocol","pages":["/docs-protocol","/","/profile","/gallery","/upload"]},{"name":"withdraw_pending_funds","kind":"act","impl":"imperative","description":"Withdraw the ETH ArtSoul holds for the connected wallet - sale proceeds, royalties and returned deposits - to that same wallet. Requires a connected wallet and the agent wallet permission.","inputSchema":{"type":"object","properties":{}},"hasHandler":true,"hasExecute":true,"__source":"spec","executable":true,"handlerField":"execute","page":"/docs-protocol","pages":["/docs-protocol","/","/profile","/gallery","/upload"]},{"name":"revoke_wallet_access","kind":"act","impl":"imperative","description":"Take away this page AI agent's ability to open the wallet in this browser. Reading continues; any wallet action needs the person to grant access again with their own click.","inputSchema":{"type":"object","properties":{}},"hasHandler":true,"hasExecute":true,"__source":"spec","executable":true,"handlerField":"execute","page":"/docs-protocol","pages":["/docs-protocol","/","/profile","/gallery","/upload"]},{"name":"prepare_artwork_registration","kind":"act","impl":"imperative","description":"Prepare publishing a new artwork on ArtSoul: validate the details, open the publish page and hand the action to the person. This tool CANNOT upload a file or sign a registration - the person attaches the media and signs in their own wallet.","inputSchema":{"type":"object","properties":{"title":{"type":"string","description":"Artwork title."},"description":{"type":"string","description":"Short description of the work."}},"required":["title"]},"hasHandler":true,"hasExecute":true,"__source":"spec","executable":true,"handlerField":"execute","page":"/docs-protocol","pages":["/docs-protocol","/","/profile","/gallery","/upload"]}],"category":"Commerce","favicon":"/favicons/artsoulprotocol.com.png","apiSurface":"spec","toolCount":19}}