Skill: jolestar/helius-openapi-skill (version 1.0.0)

--- name: helius-openapi-skill description: Operate Helius Wallet API reads through UXC with a curated OpenAPI schema, API-key auth, and read-first guardrails. --- # Helius Wallet API Skill Use this skill to run Helius Wallet API operations through `uxc` + OpenAPI. Reuse the `uxc` skill for shared execution, auth, and error-handling guidance. ## Prerequisites - `uxc` is installed and available in `PATH`. - Network access to `https://api.helius.xyz`. - Access to the curated OpenAPI schema URL: - `https://raw.githubusercontent.com/holon-run/uxc/main/skills/helius-openapi-skill/references/helius-wallet.openapi.json` - A Helius API key. ## Scope This skill covers a read-first Helius Wallet API surface: - wallet identity lookup - batch identity lookup - wallet balances - wallet history - wallet transfers - wallet funding source lookup This skill does **not** cover: - Helius RPC, DAS, or WebSocket surfaces - transaction submission - webhook setup - the broader Helius platform beyond the selected wallet intelligence endpoints ## Authentication Helius accepts API keys by query parameter or header. This skill standardizes on `X-Api-Key` header auth. Configure one API-key credential and bind it to `api.helius.xyz`: ```bash uxc auth credential set helius \ --auth-type api_key \ --api-key-header X-Api-Key \ --secret-env HELIUS_API_KEY uxc auth binding add \ --id helius \ --host api.helius.xyz \ --scheme https \ --credential helius \ --priority 100 ``` Validate the active mapping when auth looks wrong: ```bash uxc auth binding match https://api.helius.xyz ``` ## Core Workflow 1. Use the fixed link command by default: - `command -v helius-openapi-cli` - If missing, create it: ```bash uxc link helius-openapi-cli https://api.helius.xyz \ --schema-url https://raw.githubusercontent.com/holon-run/uxc/main/skills/helius-openapi-skill/references/helius-wallet.openapi.json ``` - `helius-openapi-cli -h` 2. Inspect operation schema first: - `helius-openapi-cli get:/v1/wallet/{wallet}/identity -h` - `helius-openapi-cli post:/v1/wallet/batch-identity -h` - `helius-openapi-cli get:/v1/wallet/{wallet}/balances -h` 3. Prefer narrow validation before broader reads: - `helius-openapi-cli get:/v1/wallet/{wallet}/identity wallet=HXsKP7wrBWaQ8T2Vtjry3Nj3oUgwYcqq9vrHDM12G664` - `helius-openapi-cli get:/v1/wallet/{wallet}/funded-by wallet=HXsKP7wrBWaQ8T2Vtjry3Nj3oUgwYcqq9vrHDM12G664` - `helius-openapi-cli get:/v1/wallet/{wallet}/balances wallet=HXsKP7wrBWaQ8T2Vtjry3Nj3oUgwYcqq9vrHDM12G664 page=1 limit=20 showNative=true` 4. Execute with key/value parameters: - `helius-openapi-cli post:/v1/wallet/batch-identity addresses:='[[REDACTED_SECRET]]'` - `helius-openapi-cli get:/v1/wallet/{wallet}/history wallet=HXsKP7wrBWaQ8T2Vtjry3Nj3oUgwYcqq9vrHDM12G664 limit=20` - `helius-openapi-cli get:/v1/wallet/{wallet}/transfers wallet=HXsKP7wrBWaQ8T2Vtjry3Nj3oUgwYcqq9vrHDM12G664 limit=20` - For `addresses:='[...]'`, keep shell quoting in mind. If your shell mangles that form, pass the JSON array as a bare positional payload instead. ## Operation Groups ### Wallet Identity - `get:/v1/wallet/{wallet}/identity` - `post:/v1/wallet/batch-identity` - `get:/v1/wallet/{wallet}/funded-by` ### Wallet Activity - `get:/v1/wallet/{wallet}/balances` - `get:/v1/wallet/{wallet}/history` - `get:/v1/wallet/{wallet}/transfers` ## Guardrails - Keep automation on the JSON output envelope; do not use `--text`. - Parse stable fields first: `ok`, `kind`, `protocol`, `data`, `error`. - Treat this v1 skill as read-only. Do not imply RPC write methods, transaction sending, or webhooks. - Helius labels the Wallet API as beta. Expect response shape drift and keep parsers focused on stable fields. - Start with small `limit` values before paginating large histories or transfer crawls. - Identity and funded-by lookups can return 404-style misses for unknown wallets; treat that as a data absence case before assuming auth failure. - `helius-openapi-cli <operation> ...` is equivalent to `uxc https://api.helius.xyz --schema-url <helius_openapi_schema> <operation> ...`. ## References - Usage patterns: `references/usage-patterns.md` - Curated OpenAPI schema: `references/helius-wallet.openapi.json` - Helius authentication docs: https://www.helius.dev/docs/api-reference/authentication - Helius Wallet API docs: https://www.helius.dev/docs/api-reference/wallet-api

path: agents/openai.yaml
content: interface:
  display_name: "Helius Wallet API"
  short_description: "Operate Helius Solana wallet intelligence reads via UXC + curated OpenAPI schema"
  default_prompt: "Use $helius-openapi-skill to discover and execute Helius Wallet API read-only operations through UXC with X-Api-Key auth and beta-surface guardrails."


path: references/helius-wallet.openapi.json
content: {
  "openapi": "3.0.3",
  "info": {
    "title": "Helius Wallet API",
    "version": "1.0.0",
    "description": "Curated Helius Wallet API beta operations for UXC."
  },
  "servers": [
    {
      "url": "https://api.helius.xyz"
    }
  ],
  "paths": {
    "/v1/wallet/{wallet}/identity": {
      "get": {
        "operationId": "getWalletIdentity",
        "summary": "Get wallet identity",
        "parameters": [
          {
            "name": "wallet",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Wallet identity",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Identity"
                }
              }
            }
          }
        }
      }
    },
    "/v1/wallet/batch-identity": {
      "post": {
        "operationId": "postWalletBatchIdentity",
        "summary": "Batch wallet identity lookup",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "addresses"
                ],
                "properties": {
                  "addresses": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "minItems": 1
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Wallet identities",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Identity"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/wallet/{wallet}/balances": {
      "get": {
        "operationId": "getWalletBalances",
        "summary": "Get wallet balances",
        "parameters": [
          {
            "name": "wallet",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100
            }
          },
          {
            "name": "showZeroBalance",
            "in": "query",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "showNative",
            "in": "query",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "showNfts",
            "in": "query",
            "schema": {
              "type": "boolean"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Wallet balances",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BalancesResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/wallet/{wallet}/history": {
      "get": {
        "operationId": "getWalletHistory",
        "summary": "Get wallet history",
        "parameters": [
          {
            "name": "wallet",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100
            }
          },
          {
            "name": "before",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "type",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "tokenAccounts",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Wallet history",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaginatedDataResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/wallet/{wallet}/transfers": {
      "get": {
        "operationId": "getWalletTransfers",
        "summary": "Get wallet transfers",
        "parameters": [
          {
            "name": "wallet",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Wallet transfers",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaginatedDataResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/wallet/{wallet}/funded-by": {
      "get": {
        "operationId": "getWalletFundedBy",
        "summary": "Get wallet funding source",
        "parameters": [
          {
            "name": "wallet",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Wallet funding source",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FundedBy"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "XApiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Api-Key"
      }
    },
    "schemas": {
      "Identity": {
        "type": "object",
        "additionalProperties": true,
        "properties": {
          "address": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "category": {
            "type": "string"
          },
          "type": {
            "type": "string"
          }
        }
      },
      "BalanceRow": {
        "type": "object",
        "additionalProperties": true,
        "properties": {
          "mint": {
            "type": "string"
          },
          "symbol": {
            "type": "string"
          },
          "balance": {
            "type": [
              "number",
              "string",
              "null"
            ]
          },
          "usdValue": {
            "type": [
              "number",
              "null"
            ]
          },
          "pricePerToken": {
            "type": [
              "number",
              "null"
            ]
          }
        }
      },
      "BalancesResponse": {
        "type": "object",
        "additionalProperties": true,
        "properties": {
          "wallet": {
            "type": "string"
          },
          "totalUsdValue": {
            "type": [
              "number",
              "null"
            ]
          },
          "page": {
            "type": "integer"
          },
          "limit": {
            "type": "integer"
          },
          "balances": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/BalanceRow"
            }
          }
        }
      },
      "PaginatedDataResponse": {
        "type": "object",
        "additionalProperties": true,
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          },
          "pagination": {
            "type": "object",
            "additionalProperties": true
          }
        }
      },
      "FundedBy": {
        "type": "object",
        "additionalProperties": true,
        "properties": {
          "funder": {
            "type": "string"
          },
          "funderName": {
            "type": "string"
          },
          "funderType": {
            "type": "string"
          },
          "amount": {
            "type": [
              "number",
              "string",
              "null"
            ]
          },
          "timestamp": {
            "type": [
              "integer",
              "null"
            ]
          },
          "signature": {
            "type": "string"
          }
        }
      }
    }
  },
  "security": [
    {
      "XApiKey": []
    }
  ]
}


path: references/usage-patterns.md
content: # Helius Wallet API Skill - Usage Patterns

## Link Setup

```bash
command -v helius-openapi-cli
uxc link helius-openapi-cli https://api.helius.xyz \
  --schema-url https://raw.githubusercontent.com/holon-run/uxc/main/skills/helius-openapi-skill/references/helius-wallet.openapi.json
helius-openapi-cli -h
```

## Auth Setup

```bash
uxc auth credential set helius \
  --auth-type api_key \
  --api-key-header X-Api-Key \
  --secret-env HELIUS_API_KEY

uxc auth binding add \
  --id helius \
  --host api.helius.xyz \
  --scheme https \
  --credential helius \
  --priority 100
```

Validate the binding:

```bash
uxc auth binding match https://api.helius.xyz
```

## Read Examples

```bash
# Identify a wallet with a known label
helius-openapi-cli get:/v1/wallet/{wallet}/identity \
  wallet=HXsKP7wrBWaQ8T2Vtjry3Nj3oUgwYcqq9vrHDM12G664

# Batch identity lookup for one or more addresses
helius-openapi-cli post:/v1/wallet/batch-identity \
  addresses:='[[REDACTED_SECRET]]'

# If your shell does not preserve :='[...]' quoting well, pass the same body as bare JSON
helius-openapi-cli post:/v1/wallet/batch-identity \
  '{"addresses":[[REDACTED_SECRET]]}'

# Read balances with a small page size first
helius-openapi-cli get:/v1/wallet/{wallet}/balances \
  wallet=HXsKP7wrBWaQ8T2Vtjry3Nj3oUgwYcqq9vrHDM12G664 \
  page=1 \
  limit=20 \
  showNative=true

# Read recent wallet history
helius-openapi-cli get:/v1/wallet/{wallet}/history \
  wallet=HXsKP7wrBWaQ8T2Vtjry3Nj3oUgwYcqq9vrHDM12G664 \
  limit=20

# Read recent transfers
helius-openapi-cli get:/v1/wallet/{wallet}/transfers \
  wallet=HXsKP7wrBWaQ8T2Vtjry3Nj3oUgwYcqq9vrHDM12G664 \
  limit=20

# Discover the wallet's original funding source
helius-openapi-cli get:/v1/wallet/{wallet}/funded-by \
  wallet=HXsKP7wrBWaQ8T2Vtjry3Nj3oUgwYcqq9vrHDM12G664
```

## Fallback Equivalence

- `helius-openapi-cli <operation> ...` is equivalent to
  `uxc https://api.helius.xyz --schema-url <helius_openapi_schema> <operation> ...`.


path: scripts/validate.sh
content: #!/usr/bin/env bash
set -euo pipefail

ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../../.." && pwd)"
SKILL_DIR="${ROOT_DIR}/skills/helius-openapi-skill"
SKILL_FILE="${SKILL_DIR}/SKILL.md"
OPENAI_FILE="${SKILL_DIR}/agents/openai.yaml"
USAGE_FILE="${SKILL_DIR}/references/usage-patterns.md"
SCHEMA_FILE="${SKILL_DIR}/references/helius-wallet.openapi.json"

fail() {
  printf '[validate] error: %s\n' "$*" >&2
  exit 1
}

need_cmd() {
  command -v "$1" >/dev/null 2>&1 || fail "required command not found: $1"
}

need_cmd jq
need_cmd rg

for file in "${SKILL_FILE}" "${OPENAI_FILE}" "${USAGE_FILE}" "${SCHEMA_FILE}"; do
  [[ -f "${file}" ]] || fail "missing required file: ${file}"
done

jq -e '.openapi and .paths and .components' "${SCHEMA_FILE}" >/dev/null 2>&1 || fail 'invalid OpenAPI schema JSON or missing .openapi/.paths/.components'
jq -e '.paths["/v1/wallet/{wallet}/identity"] and .paths["/v1/wallet/batch-identity"] and .paths["/v1/wallet/{wallet}/balances"]' "${SCHEMA_FILE}" >/dev/null 2>&1 || fail 'OpenAPI schema missing expected Helius wallet paths'
jq -e '.paths["/v1/wallet/batch-identity"].post and .paths["/v1/wallet/{wallet}/history"].get and .paths["/v1/wallet/{wallet}/funded-by"].get' "${SCHEMA_FILE}" >/dev/null 2>&1 || fail 'OpenAPI schema must expose expected GET/POST operations'

rg -q '^name:\s*helius-openapi-skill\s*$' "${SKILL_FILE}" || fail 'invalid skill name'
rg -q '^description:\s*.+' "${SKILL_FILE}" || fail 'missing description'

rg -q 'command -v helius-openapi-cli' "${SKILL_FILE}" || fail 'missing link-first command check'
rg -q 'uxc link helius-openapi-cli https://api.helius.xyz' "${SKILL_FILE}" || fail 'missing fixed link create command'
rg -q -- '--schema-url https://raw.githubusercontent.com/holon-run/uxc/main/skills/helius-openapi-skill/references/helius-wallet.openapi.json' "${SKILL_FILE}" || fail 'missing schema-url guidance'
rg -F -q 'helius-openapi-cli post:/v1/wallet/batch-identity -h' "${SKILL_FILE}" || fail 'missing operation-level help example'
rg -q -- '--api-key-header X-Api-Key' "${SKILL_FILE}" || fail 'missing api key setup'
rg -q 'uxc auth binding match https://api.helius.xyz' "${SKILL_FILE}" || fail 'missing binding match check'
rg -q 'beta' "${SKILL_FILE}" || fail 'missing beta surface guardrail'

if rg -q -- "--args\\s+'\\{" "${SKILL_FILE}" "${USAGE_FILE}"; then
  fail 'found banned legacy JSON argument pattern'
fi

rg -q '^\s*display_name:\s*"Helius Wallet API"\s*$' "${OPENAI_FILE}" || fail 'missing display_name'
rg -q '^\s*short_description:\s*".+"\s*$' "${OPENAI_FILE}" || fail 'missing short_description'
rg -q '^\s*default_prompt:\s*".*\$helius-openapi-skill.*"\s*$' "${OPENAI_FILE}" || fail 'default_prompt must mention $helius-openapi-skill'

echo "skills/helius-openapi-skill validation passed"


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)