Claw buyback

Accept an instant buyback offer on a claw item you own — two-step init and finish flow.

Sell a claw item back at the listed buyback price. The flow mirrors the web app: initialize a session with unsigned transactions, sign them with your wallet, then submit for co-signing and broadcast.

Scope required: marketplace.take-claw-bid on both steps.

Overview

Step	Endpoint	Purpose
1	POST /api/marketplace/transaction/take-claw-bid-init	Create a session and receive transactions to sign
2	POST /api/marketplace/transaction/take-claw-bid-finish	Submit signed transactions for settlement

Sessions expire 5 minutes after creation. If a session expires, call init again.

---

Step 1 — Initialize

Rate-limited to 1 request per 5 seconds per API key.

Request body

mint_address · string · required

Mint address (item ID) of the claw item you want to sell back. The item must have an active buyback offer for your linked wallet.

Example request

POST /api/marketplace/transaction/take-claw-bid-init
X-API-Key: phy_your_secret_key
Content-Type: application/json

{
  "mint_address": "9XnY...mint_address"
}

Response

200

{
  "session_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "txV0s": [
    "base64_serialized_versioned_transaction..."
  ]
}

session_id · string

Pass to the finish endpoint. Valid for 5 minutes.

txV0s · array

Versioned transactions to deserialize, sign with your Solana wallet, and serialize back to byte arrays for the finish call.

Error responses

Status	Example	Cause
400	{ "error": "Invalid buyback offer" }	No offer or multiple offers for this item
404	{ "error": "No wallets found" }	No linked wallet on your account
401	{ "message": "Invalid or missing credentials" }	Missing or invalid API key
429	{ "message": "Rate limit exceeded" }	More than one init per 5 seconds

---

Step 2 — Finish

Rate-limited to 1 request per second per API key.

Request body

session_id · string · required

Session ID from the init response.

txs · array · required

The txV0s from init, deserialized, signed with your wallet, and re-serialized as byte arrays.

chain · string

For EVM items, pass the chain slug. Omit for Solana (default).

Example request

POST /api/marketplace/transaction/take-claw-bid-finish
X-API-Key: phy_your_secret_key
Content-Type: application/json

{
  "session_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "txs": [[/* signed VersionedTransaction bytes */]]
}

Response

200

{
  "tx_status": "success"
}

{
  "tx_status": "success"
}

tx_status · string

"success" when the buyback settled on-chain. "failed" if broadcast failed.

Error responses

Status	Example	Cause
400	{ "error": "Session not found" }	Invalid session_id
400	{ "error": "Session expired" }	More than 5 minutes since init
400	{ "error": "Session does not belong to this user" }	Session created under a different account
400	{ "error": "Failed to submit transaction" }	On-chain submission failed
403	{ "error": "Session does not belong to this user" }	Account mismatch
401	{ "message": "Invalid or missing credentials" }	Missing or invalid API key
429	{ "message": "Rate limit exceeded" }	More than one finish per second

Integration flow

Notes

• The item must be in your inventory with an active claw buyback offer at the current price
• USDC proceeds are sent to your linked wallet as part of the settlement transaction
• Calling finish with a session that already succeeded returns { "tx_status": "success" } without re-submitting