> For the complete documentation index, see [llms.txt](https://dogex-3.gitbook.io/dogex-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://dogex-3.gitbook.io/dogex-docs/under-the-hood-smart-contract-api.md).

# Under the Hood (Smart Contract API)

## Under the Hood: Where the Magic Reside

### Opening Positions: Like Opening Pandora's Box

#### `openPosition()`: The Point of No Return

Welcome to the function that could either enrich you or teach humility.

**Function Signature:**

```solidity
function openPosition(
    uint256 _collateralAmount, // Your tribute to the crypto market
    uint256 _sizeDelta, // Size of your ambition
    bool _isLong // True for bullish, False for bearish
) external nonReentrant
```

#### Parameters Explained:

* **`_collateralAmount`**: Your USDC contribution (range: 1-1000). Consider it your offering to market volatility.
* **`_sizeDelta`**: Desired position size. The larger the number, the quicker you might face liquidation.
* **`_isLong`**:
  * `true`: "DOGE is destined to hit $1!"
  * `false`: "I've read this story before."

#### Requirements (Rules for Risk Management):

1. No existing positions (one risk at a time).
2. Leverage must be between 10x-200x.
3. Collateral must be within the valid range.
4. Necessary USDC balance (check wallet, not dreams).

#### Events Emitted:

* **`PositionOpened(user, size, collateral, entryPrice, isLong)`**: Signifying a new contender in the crypto market.

***

## Closing Positions: The Walk of Shame (or Glory)

It's decision time: ramen or lobster?

### Functions Overview

#### `closePosition()`

**What Happens:**\
Calculates your PnL (Profit and Loss, aka "Pain and Suffering").

* **Profit:** Congratulations, you've overcome the odds!
* **Loss:** Join the rest; consolation t-shirts available.

**Requirements:**

* Must have an active position.
* Contract must have sufficient USDC if your position is profitable.

#### `getPosition() - The Reality Check Function`

Gets your position and current PnL. Warning: May cause regret.

**Returns:** Struct `PositionWithPnL`

* `uint256 size`: Size of your investment.
* `uint256 collateral`: Your collateral.
* `uint256 entryPrice`: The haunting entry price.
* `bool isLong`: Your market stance.
* `bool isActive`: If you're still in the game.
* `int256 pnl`: The number that makes you laugh or cry.

#### Liquidation System (Where Dreams Go to Die)

**`liquidatePosition() - The Grim Reaper Function`**

Activates when your position crashes disastrously.

**Function:** `liquidatePosition(address _user) external nonReentrant`

### How Liquidation Works

#### Standard Liquidation

* **Loss Threshold**: Your position loses 90% of its value.
* **Liquidator's Role**: A liquidator calls the liquidation function.
  * **Reward**: They earn a 5% reward for executing the liquidation.
* **Remaining Value**: You receive any value left (if anything).
* **Reflection**: It's a time to reconsider life decisions.

#### batchLiquidate() - Mass Destruction Mode

* **Purpose**: To liquidate multiple positions simultaneously during market downturns.
* **Function Signature**:

  ```solidity
  function batchLiquidate(uint256 maxLiquidations) external nonReentrant returns (uint256)
  ```
* **Ideal For**:
  * Market crash days
  * Liquidation bot operators
  * Those who find humor in misfortune

#### isLiquidatable() - The Danger Detector

* **Functionality**: Determines if a position is at risk of liquidation.
* **Function Signature**:

  ```solidity
  function isLiquidatable(address _user) public view returns (bool)
  ```
* **Outcome**: Returns `true` if liquidation is imminent.

###


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://dogex-3.gitbook.io/dogex-docs/under-the-hood-smart-contract-api.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.