---
name: memeliquid
version: 1.3.0
description: Detailed execution guide for AI agents on MemeLiquid perpetuals, including open/reduce/close lifecycle, risk gating, and user-signed transaction policy.
homepage: https://memeliquid.io
---

# MemeLiquid

On-chain perpetual trading on Solana. This skill helps agents discover markets, calculate safe trade plans, and execute only user-approved transactions.

## Skill Files

| File | URL |
|------|-----|
| **SKILL.md** (this file) | `https://memeliquid.io/skill.md` |
| **skill.json** (metadata) | `https://memeliquid.io/skill.json` |
| **IDL** | `https://memeliquid.io/idl/percolator-prog.json` |
| **OpenAPI Agent Spec** | `https://memeliquid.io/openapi.agent.json` |

## Base URLs

- UI: `https://memeliquid.io`
- API: `https://api-mainnet.memeliquid.io`

## Agent Quickstart

1. Fetch `GET /api/markets` and pick a valid `market_id`.
2. Fetch `GET /api/market-book/{market_id}` to evaluate LP depth and impact.
3. Build a planning payload using the schemas in `skill.json` (`openapi_lite`).
4. Run risk guardrails and display a human-readable trade plan.
5. Build transaction payload from IDL and request user wallet signature.
6. Submit signed transaction and return tx signature + confirmation status.

## Compatibility

- OpenAPI: `3.1.0`
- JSON Schema: `2020-12`
- Minimum agent features:
  - HTTP GET support
  - JSON schema validation
  - Wallet signature flow support

## Data Freshness and Polling

- Recommended polling interval: every `5s`.
- Oracle staleness threshold: `<= 30s` (reject writes when stale).
- Suggested retry policy for read failures: `3` retries with backoff `300ms`, `900ms`, `1800ms`.

## Programs

- Trade Program: `DP2EbA2v6rmkmNieZpnjumXosuXQ93r9jyb9eSzzkf1x`
- Matcher Program: `FbTaGPKcrgKXQx3t5WekJcAyH5cL9s8kvVccvZC3jg8r`
- Vault-LP Program: `MEMELPhk8VXcqAPzY9ooyHGQKbTLpEkpavJ2XQJSsP3`

## Security Policy (Critical)

- Never hold or request a user's private key.
- Only execute transactions signed by the user wallet.
- Never simulate "server execution" for real funds.
- Always fetch fresh market state before any write action.
- Enforce explicit risk checks before building tx payloads.
- Refuse any trade with stale data or insufficient liquidity.

## Execution Model

MemeLiquid execution is strictly **user-signed**:

- Agents can read data, compute plans, and build transaction payloads.
- Final trade execution requires wallet signature (Solflare/Phantom/etc).
- Server-side order submission is out of scope unless an explicit signed-intent API is introduced.

## Supported Markets

- `sol-usd`
- `liquid-sol`
- `buttcoin-sol`
- `whale-sol`
- `skr-sol`
- `penguin-sol`
- `ferociter-sol`
- `claude-sol`
- `punch-sol`

## Read Endpoints

### Markets Snapshot
```bash
curl https://api-mainnet.memeliquid.io/api/markets
```

### Single Market State
```bash
curl https://api-mainnet.memeliquid.io/api/markets/liquid-sol
```

### Orderbook / LP Depth
```bash
curl https://api-mainnet.memeliquid.io/api/market-book/liquid-sol
```

### Positions
```bash
curl "https://api-mainnet.memeliquid.io/api/positions/liquid-sol?active=true&limit=100"
```

### Trades
```bash
curl "https://api-mainnet.memeliquid.io/api/trades/liquid-sol?limit=50"
```

### Service Status
```bash
curl https://api-mainnet.memeliquid.io/status
```

### Earn Vaults
```bash
curl https://api-mainnet.memeliquid.io/api/vaults
```

## OpenAPI-Lite Contract

This skill has two layers:
- **HTTP Read API**: for live market and position data.
- **Local Contract**: for deterministic, agent-side trade planning schemas.

### 1) `plan_open_position` (Local Contract)

Request schema:
```json
{
  "market_id": "liquid-sol",
  "side": "LONG",
  "collateral_sol": 0.5,
  "leverage": 2,
  "max_slippage_bps": 150,
  "owner_pubkey": "USER_PUBKEY"
}
```

Response schema:
```json
{
  "ok": true,
  "risk_checks": [
    {"name": "market_exists", "pass": true},
    {"name": "oracle_fresh", "pass": true},
    {"name": "sufficient_lp_depth", "pass": true},
    {"name": "price_impact_within_limit", "pass": true}
  ],
  "estimates": {
    "entry_price": 0.000912,
    "notional_sol": 1.0,
    "fee_sol": 0.001,
    "price_impact_bps": 42
  },
  "next_action": "request_user_signature"
}
```

### 2) `plan_close_position` (Local Contract)

Request schema:
```json
{
  "market_id": "liquid-sol",
  "owner_pubkey": "USER_PUBKEY",
  "close_mode": "reduce_percent",
  "reduce_percent": 50,
  "max_slippage_bps": 150
}
```

Response schema:
```json
{
  "ok": true,
  "close_size": 420.5,
  "estimated_fee_sol": 0.0004,
  "risk_checks": [
    {"name": "position_found", "pass": true},
    {"name": "sufficient_lp_depth", "pass": true}
  ],
  "next_action": "request_user_signature"
}
```

### 3) `track_position` (Local Contract)

Request schema:
```json
{
  "market_id": "liquid-sol",
  "owner_pubkey": "USER_PUBKEY"
}
```

Response schema:
```json
{
  "position_found": true,
  "entry_price": 0.00088,
  "mark_price": 0.00091,
  "unrealized_pnl_sol": 0.12,
  "liq_distance_percent": 38.7,
  "margin_headroom_sol": 0.44
}
```

### 4) `submit_signed_transaction` (Wallet/RPC)

This operation is allowed only after user wallet signature.

Request schema:
```json
{
  "signed_tx_base64": "BASE64_TX",
  "rpc_url": "https://<rpc>"
}
```

Response schema:
```json
{
  "tx_signature": "5q...abc",
  "confirmed": true,
  "slot": 401234567
}
```

### Operation Mapping

- `get_markets` -> `GET /api/markets`
- `get_market_book` -> `GET /api/market-book/{market_id}`
- `get_positions` -> `GET /api/positions/{market_id}?active=true&owner=<pubkey>&limit=100`
- `plan_open_position` -> Local Contract (agent-side)
- `plan_close_position` -> Local Contract (agent-side)
- `track_position` -> Local Contract (agent-side)
- `submit_signed_transaction` -> Wallet or RPC submit path

## Standard Error Envelope

Use this normalized shape for all failures:

```json
{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Too many requests. Retry after delay.",
    "retryable": true,
    "details": {}
  }
}
```

`code` should map to one of:
- `NOT_FOUND`
- `RATE_LIMITED`
- `INTERNAL_ERROR`
- `STALE_DATA`
- `INSUFFICIENT_LIQUIDITY`
- `SLIPPAGE_EXCEEDED`
- `RISK_GATE_ACTIVE`

## Position Lifecycle

## 1) Open Position

Required inputs:
- `market_id`
- `side` (`LONG` or `SHORT`)
- `collateral_sol`
- `leverage`
- `max_slippage_bps`

Execution steps:
1. Read `/api/markets/:market_id` and `/api/market-book/:market_id`.
2. Validate leverage <= market max.
3. Compute projected size/notional.
4. Estimate entry + fee + impact.
5. Run risk guardrails.
6. Present final summary and request user confirmation.
7. Build on-chain trade tx.
8. User signs and submits.

Output:
- `tx_signature`
- `entry_estimate`
- `fee_estimate`
- `risk_summary`

## 2) Reduce / Close Position

Required inputs:
- `market_id`
- `position_owner`
- `target_close_mode` (`close_all` or `reduce_percent`)

Execution steps:
1. Read `/api/positions/:market_id?active=true`.
2. Identify user position/account index.
3. Compute inverse trade size.
4. Re-check depth/slippage/fee.
5. Build tx and request user signature.
6. Return close result and remaining size.

## 3) Track Position

Polling sources:
- `/api/positions/:market_id`
- `/api/markets/:market_id`
- `/api/trades/:market_id`

Track fields:
- mark price
- unrealized pnl
- liquidation proximity
- margin headroom
- fill history

## Risk Guardrails

Hard checks before write:
- Ensure market exists and is active.
- Oracle/price signal must be fresh.
- Leverage must be within limits.
- LP depth must cover requested size.
- Projected slippage/impact must be <= user cap.
- Reject if engine is in risk-reduction-only mode.

Soft policy:
- Extra user confirmation for leverage > 3x.
- Extra confirmation for large notional trades.
- No automatic retry loops for failed writes.

## Suggested Agent Output Format

```markdown
Trade Plan:
- Market: <market-id>
- Side: <LONG|SHORT>
- Collateral: <amount SOL>
- Leverage: <x>
- Estimated entry: <price>
- Estimated fee: <value>
- Slippage cap: <value>
- Risk checks:
  - Market active: <PASS|FAIL>
  - Oracle freshness: <PASS|FAIL>
  - Liquidity depth: <PASS|FAIL>
  - Slippage cap: <PASS|FAIL>
  - Engine risk gate: <PASS|FAIL>

If confirmed, sign and submit transaction.
```

## Errors and Recovery

Common failure classes:
- `stale_data`: re-fetch market/book and re-price.
- `insufficient_liquidity`: reduce size or leverage.
- `slippage_exceeded`: ask user for lower size or wider cap.
- `risk_gate_active`: allow only risk-reducing actions.
- `tx_reverted`: show exact on-chain error and stop auto-retry.

## Minimal Agent Playbooks

### Playbook: Open Long
1. Read market + book.
2. Compute `size = collateral * leverage / entry_price`.
3. Validate guardrails.
4. Show plan.
5. Build tx and request signature.
6. Submit and return tx hash.

### Playbook: Close All
1. Read active user position.
2. Determine inverse side and full size.
3. Validate slippage/depth.
4. Build close tx.
5. Request signature and submit.

### Playbook: Monitor Risk
1. Poll market + positions every N seconds.
2. Trigger warning when liquidation distance below threshold.
3. Suggest de-lever / partial close with explicit plan.

## End-to-End Examples

### Example A: Open LONG (User-Signed)
1. `GET /api/markets` -> choose `liquid-sol`.
2. `GET /api/market-book/liquid-sol` -> ensure depth and impact are acceptable.
3. Build local `plan_open_position`:
   - `side=LONG`, `collateral_sol=0.5`, `leverage=2`, `max_slippage_bps=150`.
4. Validate all risk checks are `PASS`.
5. Build transaction from IDL.
6. Request wallet signature.
7. Submit signed tx via wallet/RPC.
8. Return:
   - tx signature
   - projected entry/fee
   - post-trade risk summary

### Example B: Close 50% Position (User-Signed)
1. `GET /api/positions/liquid-sol?active=true&owner=<pubkey>`.
2. Build local `plan_close_position` with `close_mode=reduce_percent`, `reduce_percent=50`.
3. Verify depth/slippage checks.
4. Build close transaction from IDL.
5. Request wallet signature.
6. Submit and confirm.
7. Return:
   - tx signature
   - remaining size
   - updated unrealized pnl and liquidation distance

## Optional Future API (if enabled)

If a signed-intent server API is added later:
- `POST /api/agent/build-order`
- `POST /api/agent/submit-signed`
- `GET /api/agent/order/:id`

Until then, treat this skill as read + user-signed execution orchestration.

## Changelog

### 1.3.0
- Added compatibility section and polling/freshness guidance.
- Added standardized error envelope for agent implementations.
- Added end-to-end LONG and CLOSE user-signed execution examples.
- Linked to machine-readable OpenAPI contract.