Jupiter Skill for OpenClaw

Execute Jupiter API operations on Solana - fetch quotes, sign transactions, execute swaps, prediction markets. Use when implementing token swaps, DCA, limit orders, lending, prediction markets, or any Jupiter integration. Includes scripts for Ultra and Metis swap flows.

# Jupiter API Skill

Execute Jupiter API operations through 4 utility scripts for fetching data, signing transactions, and executing swaps on Solana.

**Base URL**: `https://api.jup.ag`

## Quick Reference

| Task | Script | Example |
|------|--------|---------|
| Fetch any Jupiter API | `fetch-api.ts` | `pnpm fetch-api -e /ultra/v1/search -p '{"query":"SOL"}'` |
| Sign a transaction | `wallet-sign.ts` | `pnpm wallet-sign -t "BASE64_TX" -w ~/.config/solana/id.json` |
| Execute Ultra order | `execute-ultra.ts` | `pnpm execute-ultra -r "REQUEST_ID" -t "SIGNED_TX"` |
| Send tx to RPC | `send-transaction.ts` | `pnpm send-transaction -t "SIGNED_TX"` |

## Setup

Install dependencies before using scripts:
```bash
cd /path/to/jup-skill
pnpm install
```

Run `pnpm install` once per clone (and again after dependency changes) before any `pnpm fetch-api`, `pnpm wallet-sign`, `pnpm execute-ultra`, or `pnpm send-transaction` command.

## API Key Setup

**ALWAYS required.** All Jupiter API endpoints require an `x-api-key` header.

1. Visit [portal.jup.ag](https://portal.jup.ag)
2. Create account and generate API key
3. Set via environment variable (recommended):
   ```bash
   export JUP_API_KEY=your_api_key_here
   ```
   Or pass via `--api-key` flag on each command.

## Wallet Safety

Signing requires access to a local Solana wallet JSON file (`--wallet`), which contains private key material.

- Do not use a high-value wallet for automation.
- Prefer a dedicated low-balance wallet for this workflow.
- For testing, prefer ephemeral keys.
- If your setup supports it, prefer hardware signing over raw key files.

## Scripts

### fetch-api.ts

Fetch data from any Jupiter API endpoint.

```bash
# Search for tokens
pnpm fetch-api -e /ultra/v1/search -p '{"query":"SOL"}'

# Get Ultra swap order (quote + unsigned transaction)
pnpm fetch-api -e /ultra/v1/order -p '{
  "inputMint": "So11111111111111111111111111111111111111112",
  "outputMint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
  "amount": "1000000",
  "taker": "YOUR_WALLET_ADDRESS"
}'

# Get Metis quote
pnpm fetch-api -e /swap/v1/quote -p '{
  "inputMint": "So11111111111111111111111111111111111111112",
  "outputMint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
  "amount": "1000000",
  "slippageBps": "50"
}'

# POST request (for Metis swap transaction)
pnpm fetch-api -e /swap/v1/swap -m POST -b '{
  "quoteResponse": {...},
  "userPublicKey": "YOUR_WALLET"
}'
```

**Arguments:**
- `-e, --endpoint` (required): API path, e.g., `/ultra/v1/order`
- `-p, --params`: Query params (GET) or body (POST) as JSON string
- `-b, --body`: Request body for POST requests
- `-m, --method`: HTTP method, `GET` (default) or `POST`
- `-k, --api-key`: API key (or use `JUP_API_KEY` env var)

### wallet-sign.ts

Sign transactions using a local wallet file.

> **SECURITY NOTE**: The `--wallet` flag is required. This script does not accept private keys via command line arguments to prevent exposure in shell history and process listings.

```bash
# Using Solana CLI wallet (JSON array format)
pnpm wallet-sign -t "BASE64_UNSIGNED_TX" --wallet ~/.config/solana/id.json

# Tilde expansion is supported
pnpm wallet-sign -t "BASE64_UNSIGNED_TX" --wallet ~/my-wallets/trading.json
```

**Arguments:**
- `-t, --unsigned-tx` (required): Base64-encoded unsigned transaction
- `-w, --wallet` (required): Path to Solana CLI JSON wallet file (supports ~ for home directory)

**Output:** Signed transaction (base64) to stdout.

### execute-ultra.ts

Execute Ultra orders after signing.

```bash
pnpm execute-ultra -r "REQUEST_ID_FROM_ORDER" -t "BASE64_SIGNED_TX"
```

**Arguments:**
- `-r, --request-id` (required): Request ID from `/ultra/v1/order` response
- `-t, --signed-tx` (required): Base64-encoded signed transaction
- `-k, --api-key`: API key (or use `JUP_API_KEY` env var)

**Output:** Execution result JSON including signature and status.

### send-transaction.ts

Send signed transactions to Solana RPC. **Use for Metis swaps** (Ultra handles RPC internally).

> **Warning**: The default public Solana RPC (`api.mainnet-beta.solana.com`) is rate-limited and unreliable for production use. Use a dedicated RPC provider (Helius, QuickNode, Triton, etc.) for production applications.

```bash
# Default RPC (mainnet-beta)
pnpm send-transaction -t "BASE64_SIGNED_TX"

# Custom RPC
pnpm send-transaction -t "BASE64_SIGNED_TX" -r "https://your-rpc.com"

# With environment variable
export SOLANA_RPC_URL="https://your-rpc.com"
pnpm send-transaction -t "BASE64_SIGNED_TX"
```

**Arguments:**
- `-t, --signed-tx` (required): Base64-encoded signed transaction
- `-r, --rpc-url`: RPC endpoint (default: `https://api.mainnet-beta.solana.com`)
- `--skip-preflight`: Skip preflight checks (faster, less safe)
- `--max-retries`: Max send retries (default: 3)

**Output:** Transaction signature to stdout.

---

## Workflows

### Ultra Swap (Recommended)

Ultra is RPC-less, gasless, with automatic slippage optimization.

```
Ultra Swap Progress:
- [ ] Step 1: Get order from /ultra/v1/order
- [ ] Step 2: Sign the transaction
- [ ] Step 3: Execute via /ultra/v1/execute
- [ ] Step 4: Verify result
```

**Step 1: Get Order**

```bash
ORDER=$(pnpm fetch-api -e /ultra/v1/order -p '{
  "inputMint": "So11111111111111111111111111111111111111112",
  "outputMint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
  "amount": "1000000",
  "taker": "YOUR_WALLET_ADDRESS"
}')
echo "$ORDER"
```

Response contains `requestId` and `transaction` (base64 unsigned).

**Step 2: Sign Transaction**

Extract transaction from response and sign:

```bash
UNSIGNED_TX=$(echo "$ORDER" | jq -r '.transaction')
SIGNED_TX=$(pnpm wallet-sign -t "$UNSIGNED_TX" -w ~/.config/solana/id.json)
```

**Step 3: Execute Order**

```bash
REQUEST_ID=$(echo "$ORDER" | jq -r '.requestId')
pnpm execute-ultra -r "$REQUEST_ID" -t "$SIGNED_TX"
```

**Step 4: Verify**

Check the signature on [Solscan](https://solscan.io).

---

### Metis Swap (Advanced)

Use Metis when you need custom transaction composition or fine-grained control.

```
Metis Swap Progress:
- [ ] Step 1: Get quote from /swap/v1/quote
- [ ] Step 2: Build transaction via /swap/v1/swap
- [ ] Step 3: Sign the transaction
- [ ] Step 4: Send to RPC
- [ ] Step 5: Verify on-chain
```

**Step 1: Get Quote**

```bash
QUOTE=$(pnpm fetch-api -e /swap/v1/quote -p '{
  "inputMint": "So11111111111111111111111111111111111111112",
  "outputMint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
  "amount": "1000000",
  "slippageBps": "50"
}')
```

**Step 2: Build Transaction**

```bash
SWAP_TX=$(pnpm fetch-api -e /swap/v1/swap -m POST -b "{
  \"quoteResponse\": $QUOTE,
  \"userPublicKey\": \"YOUR_WALLET_ADDRESS\",
  \"dynamicComputeUnitLimit\": true,
  \"prioritizationFeeLamports\": \"auto\"
}")
```

**Step 3: Sign**

```bash
UNSIGNED_TX=$(echo "$SWAP_TX" | jq -r '.swapTransaction')
SIGNED_TX=$(pnpm wallet-sign -t "$UNSIGNED_TX" --wallet ~/.config/solana/id.json)
```

**Step 4: Send to RPC**

```bash
pnpm send-transaction -t "$SIGNED_TX" -r "https://your-rpc.com"
```

**Step 5: Verify**

Check signature on Solscan.

---

### Prediction Markets (Beta)

Trade on real-world event outcomes. Contracts trade $0-$1 USD, with prices reflecting outcome probability.

```
Prediction Market Flow:
- [ ] Step 1: Browse events/markets
- [ ] Step 2: Create order (buy YES/NO contracts)
- [ ] Step 3: Sign and send transaction
- [ ] Step 4: Monitor position
- [ ] Step 5: Claim winnings (if correct)
```

**Step 1: Browse Events**

```bash
# Search for events
pnpm fetch-api -e /prediction/v1/events/search -p '{"query":"election","limit":"10"}'

# List all events
pnpm fetch-api -e /prediction/v1/events -p '{"category":"politics","includeMarkets":"true"}'

# Get specific event with markets
pnpm fetch-api -e /prediction/v1/events/{eventId} -p '{"includeMarkets":"true"}'
```

**Step 2: Create Order**

```bash
# Buy YES contracts on a market
ORDER=$(pnpm fetch-api -e /prediction/v1/orders -m POST -b '{
  "ownerPubk