> ## Documentation Index
> Fetch the complete documentation index at: https://dev.phygitals.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<Note>
  **Scope required:** `marketplace.take-claw-bid` on both steps.
</Note>

## 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

<Note>
  Rate-limited to **1 request per 5 seconds** per API key.
</Note>

### Request body

<ParamField body="mint_address" type="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.
</ParamField>

### Example request

```http theme={"dark"}
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

<ResponseExample>
  ```json 200 theme={"dark"}
  {
    "session_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "txV0s": [
      "base64_serialized_versioned_transaction..."
    ]
  }
  ```
</ResponseExample>

<ResponseField name="session_id" type="string">
  Pass to the finish endpoint. Valid for 5 minutes.
</ResponseField>

<ResponseField name="txV0s" type="array">
  Versioned transactions to deserialize, sign with your Solana wallet, and serialize back to byte arrays for the finish call.
</ResponseField>

### 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

<Warning>
  Rate-limited to **1 request per second** per API key.
</Warning>

### Request body

<ParamField body="session_id" type="string" required>
  Session ID from the init response.
</ParamField>

<ParamField body="txs" type="array" required>
  The `txV0s` from init, deserialized, signed with your wallet, and re-serialized as byte arrays.
</ParamField>

<ParamField body="chain" type="string">
  For EVM items, pass the chain slug. Omit for Solana (default).
</ParamField>

### Example request

```http theme={"dark"}
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

<ResponseExample>
  ```json 200 theme={"dark"}
  {
    "tx_status": "success"
  }
  ```

  ```json 200 — already completed theme={"dark"}
  {
    "tx_status": "success"
  }
  ```
</ResponseExample>

<ResponseField name="tx_status" type="string">
  `"success"` when the buyback settled on-chain. `"failed"` if broadcast failed.
</ResponseField>

### 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

```mermaid theme={"dark"}
sequenceDiagram
    autonumber
    participant C as Your script
    participant A as Phygitals API
    participant S as Solana

    C->>A: POST …/take-claw-bid-init
    A-->>C: { session_id, txV0s }
    C->>S: Deserialize, sign txV0s
    C->>A: POST …/take-claw-bid-finish
    A-->>C: { tx_status: "success" }
```

## 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