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

# Start share merge

> Create a share merge draft. Must be signed and submitted.

Convert a complete set of outcome shares back into USDC: each `1` YES share plus `1` NO share becomes `1` USDC.

Share merges are available on open order book markets that do not have margin trading enabled. Other markets return `share_conversion_market_not_eligible`.

Creating a draft locks the YES and NO shares for `amount` until the merge finishes. Drafts expire quickly, so sign and submit promptly. An unsigned draft that expires moves to `expired` and releases the lock.

## Body Parameters

<ParamField body="market_condition_id" type="string" required>
  Market condition id.
</ParamField>

<ParamField body="amount" type="string" required>
  Complete sets to merge. This many YES shares and this many NO shares are burned and you receive this much USDC. Must be a positive multiple of the market's lot size, `10^-amount_precision` (see `amount_precision` on [Get market by condition id](/api-reference/markets/market-detail)). At most 6 decimal places.
</ParamField>

<Note>
  Sign the returned **`message`**, then call [Submit share merge](/api-reference/share-merges/submit-merge) with the hex **`signature`** (see that page). Track the result with [Get share merge by pubkey](/api-reference/share-merges/merge-detail).
</Note>

## Response

On success the API returns **`201 Created`** with a **`Location`** header pointing to `GET /share-merges/{pubkey}/`.

<ResponseField name="data" type="object">
  Created share merge draft payload.
</ResponseField>

<Expandable title="Data fields">
  <ResponseField name="pubkey" type="string">
    Share merge public key.
  </ResponseField>

  <ResponseField name="message" type="string">
    Program message to sign.
  </ResponseField>
</Expandable>

<ResponseField name="meta" type="object">
  Empty object on success for this endpoint.
</ResponseField>

<ResponseField name="error" type="object | null">
  `null` on success. Error object on failed requests.
</ResponseField>

## Errors

| Status | Slug | When |
| - | - | - |
| `400` | `invalid_request_params` | Validation failed, for example the market is not found (`details` names the field). |
| `400` | `share_conversion_market_not_eligible` | The market does not support split and merge. |
| `400` | `share_conversion_invalid_amount` | `amount` is not a positive multiple of the market's lot size. |
| `400` | `share_merge_insufficient_shares` | Your available YES or NO shares (not locked by open orders or other conversions) are below `amount`. |
| `403` | `custodial_user_trading_not_allowed` | Custodial accounts cannot use split and merge. |
| `409` | `share_conversion_market_not_open` | The market is not open. |
| `409` | `share_conversion_market_paused` | The market is paused on chain. |
| `409` | `share_merge_in_progress` | Another share merge on this market is waiting to be signed or in process. Repeating a request for an unsigned draft with the same `amount` returns that draft instead of this error. |
| `409` | `share_merge_market_has_unbacked_collateral` | Merging is temporarily unavailable on this market. |
| `503` | `gringotts_unavailable` | The signing service is temporarily unavailable. Retry shortly. |

<ResponseExample>
  ```json 201 theme={null}
  {
    "data": {
      "pubkey": "HwqEtgeDoWHLqyMQgjwj7BGWmCrZ46m6y5bALMfYcGYY",
      "message": "Program call payload to merge shares."
    },
    "meta": {},
    "error": null
  }
  ```

  ```json 400 theme={null}
  {
    "data": null,
    "meta": null,
    "error": {
      "code": -11,
      "slug": "invalid_request_params",
      "message": "Validation Error",
      "details": []
    }
  }
  ```

  ```json 400 theme={null}
  {
    "data": null,
    "meta": null,
    "error": {
      "code": 4313,
      "slug": "share_merge_insufficient_shares",
      "message": "Not enough available YES and NO shares to merge this amount.",
      "details": []
    }
  }
  ```

  ```json 401 theme={null}
  {
    "data": null,
    "meta": null,
    "error": {
      "code": -12,
      "slug": "authentication_failed",
      "message": "Invalid signature",
      "details": []
    }
  }
  ```

  ```json 403 theme={null}
  {
    "data": null,
    "meta": null,
    "error": {
      "code": -14,
      "slug": "permission_denied",
      "message": "You do not have permission to perform this action.",
      "details": []
    }
  }
  ```

  ```json 409 theme={null}
  {
    "data": null,
    "meta": null,
    "error": {
      "code": 4306,
      "slug": "share_merge_in_progress",
      "message": "A merge on this market is already in progress.",
      "details": []
    }
  }
  ```

  ```json 429 theme={null}
  {
    "data": null,
    "meta": null,
    "error": {
      "code": -17,
      "slug": "throttled",
      "message": "Request was throttled.",
      "details": []
    }
  }
  ```

  ```json 500 theme={null}
  {
    "data": null,
    "meta": null,
    "error": {
      "code": -3,
      "slug": "internal_error",
      "message": "An internal error occurred.",
      "details": []
    }
  }
  ```

  ```json 503 theme={null}
  {
    "data": null,
    "meta": null,
    "error": {
      "code": 3042,
      "slug": "gringotts_unavailable",
      "message": "The signing service is temporarily unavailable. Please try again shortly.",
      "details": []
    }
  }
  ```
</ResponseExample>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.