# Create a LithosDex pool

`POST /dex/pools/create` · Lithos client API · Lithos Dex · requires the `api_key` header

Source: https://lithosprotocol.org/docs/api/create-ld-pool

Sends four transactions in turn: the pool NFT mint, the vault NFT mint, the mint of the NFT that owns the provision, and the genesis, which creates the pool, its vault and this wallet's provision. Every box one transaction passes to the next is held at the wallet before the first send, so nothing else spends it. The chain stops at the first transaction the node does not accept, and reports those after it as `unsent`. Besides the locked share, a token/token pool's boxes hold 6.3 ERG and 2.3 ERG for storage rent and its vault one unit of each token, and an ERG/token vault holds 0.1 ERG, none of it recoverable. Needs `acknowledgeLocked`. The pool is listed once its genesis is in a block.

## Request body

`LDPoolCreateExecuteRequest`, application/json.

- `tokenX` (string, required): ERG for an ERG/token pool, or a token/token pool's first token id
- `tokenY` (string, required): The pool's other token id
- `amountX` (string, required): The pool's reserve of X at genesis; nanoERG for ERG, at least 0.01 ERG
- `amountY` (string, required)
- `feeParams` (LDFeeParams): Fee numerators over `feeDenom`. `dexFeeNum` stays in the pool; `ergFeeNum` / `tokenFeeNum` are set aside for liquidity providers. 
  - `dexFeeNum` (integer · int64, required)
  - `ergFeeNum` (integer · int64, required)
  - `tokenFeeNum` (integer · int64, required)
  - `feeDenom` (integer · int64, required): Denominator of every numerator above
- `acknowledgeLocked` (boolean, required): Must be true: the pool's own boxes and its locked share can never be taken back

## Responses

### 200: The four sends, as far as they went

`LDPoolCreated`

- `outcome` (string, required, one of accepted, rejected, uncertain, unsent): accepted when all four were, else the first step's that was not
- `kind` (string, required, one of n2t, t2t)
- `poolNFT` (string, required)
- `vaultNFT` (string, required)
- `provToken` (string, required)
- `ownerNFT` (string, required): The NFT in this wallet that owns the creator's provision
- `provisionBoxId` (string, required): The creator's provision, which genesis creates
- `steps` (LDPoolCreateStep[], required)
  - `step` (string, required, one of POOL_NFT, VAULT_NFT, OWNER_NFT, GENESIS)
  - `txId` (string, required)
  - `outcome` (string, required, one of accepted, rejected, uncertain, unsent): unsent: an earlier transaction was not accepted
  - `reason` (string): The node's refusal, or why the transaction was not sent

### 400: The request is malformed, names ERG as tokenY or one token twice, offers an ERG reserve under 0.01 ERG, gives fees out of bounds, or lacks acknowledgeLocked.

`ApiError`

- `error` (integer, required): Error code
- `reason` (string, required): Error message explaining the reason of the error
- `detail` (string, required): Detailed error description

### 403: Missing or wrong api_key

`ApiError`

- `error` (integer, required): Error code
- `reason` (string, required): Error message explaining the reason of the error
- `detail` (string, required): Detailed error description

### 409: The wallet's boxes moved while the chain was built. Resend.

`LDStateChangedResponse`

- `error` (integer, required)
- `reason` (string, required)
- `detail` (string, required): What moved, and what it moved to
- `poolBoxId` (string): Current pool box id
- `vaultBoxId` (string): Current vault box id
- `provisionBoxId` (string): Current provision box id

### 422: The wallet cannot cover the reserves, boxes and fees.

`ApiError`

- `error` (integer, required): Error code
- `reason` (string, required): Error message explaining the reason of the error
- `detail` (string, required): Detailed error description

### 503: The node or wallet did not answer. Nothing was sent. Retry.

`ApiError`

- `error` (integer, required): Error code
- `reason` (string, required): Error message explaining the reason of the error
- `detail` (string, required): Detailed error description

### default: Error

`ApiError`

- `error` (integer, required): Error code
- `reason` (string, required): Error message explaining the reason of the error
- `detail` (string, required): Detailed error description

## Example request

```bash
curl -X POST "http://localhost:9000/dex/pools/create" \
  -H "api_key: $LITHOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "tokenX": "string", "tokenY": "string", "amountX": "string", "amountY": "string", "feeParams": { "dexFeeNum": 9985, "ergFeeNum": 15, "tokenFeeNum": 15, "feeDenom": 10000 }, "acknowledgeLocked": true }'
```

## Example response

```json
{
  "outcome": "accepted",
  "kind": "n2t",
  "poolNFT": "string",
  "vaultNFT": "string",
  "provToken": "string",
  "ownerNFT": "string",
  "provisionBoxId": "string",
  "steps": [
    {
      "step": "POOL_NFT",
      "txId": "string",
      "outcome": "accepted",
      "reason": "string"
    }
  ]
}
```