jupiter-skill

What this skill does

# 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 '{
  "ownerPub