# okx-cex-auth

Sets up OAuth access for OKX CLI, checks the session state, and helps recover from authentication failures.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 5900 installs · ★ 195
- Author: okx
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/okx/agent-skills/tree/HEAD/skills/okx-cex-auth/SKILL.md
- Updated: 2026-10-19
- HTML: https://affpapa.org/en/nevibecode/skills/okx-cex-auth

## What it does

This skill runs the OAuth 2.0 device flow for OKX CLI. It covers initial account connection, re-authentication after a session expires, and logout.

Before a login attempt, it runs `okx config show --json` and `okx auth status --json` to inspect the selected site, API key profiles, and OAuth state. It asks for a site choice when needed, and does not start a second login while a previous flow is `pending`.

The `okx` CLI is required and can be installed with npm. An existing API key takes priority over OAuth in the CLI, so OAuth login will not start while that profile remains. This skill is not for market-data requests; use `okx-cex-market` instead.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add okx/agent-skills --skill okx-cex-auth -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/okx-cex-auth/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/okx-cex-auth/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add okx/agent-skills --skill okx-cex-auth -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/okx-cex-auth/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add okx/agent-skills --skill okx-cex-auth -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/okx-cex-auth/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install okx/agent-skills okx-cex-auth
```

2. **Manually: put the files in place**
- File: `.github/skills/okx-cex-auth/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add okx/agent-skills --skill okx-cex-auth -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/okx/agent-skills --path skills/okx-cex-auth
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/okx-cex-auth/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add okx/agent-skills --skill okx-cex-auth -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/okx/agent-skills/tree/HEAD/skills/okx-cex-auth/SKILL.md

## When to use it
- connect an OKX account through OAuth
- recover an expired OAuth session
- check OKX CLI login status
- choose an OKX site before first login
- inspect or update `okx-auth`

## Example prompts
- Connect my OKX account with OAuth.
- Check my OKX CLI login status and restore the session.
- Check whether `okx-auth` is installed and update it.

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 58a186334bc978c7.

BEGIN THIRD-PARTY FILE 58a186334bc978c7
````text
---
name: okx-cex-auth
description: "Use this skill when the user wants to 'login/log in/sign in', 'authenticate', 'authorize', 'connect OKX account', 'set up credentials', 'first time setup', 'configure okx', '登录', '授权', '认证', '连接账户', '首次配置'. Also when any OKX CLI command fails with an auth error: 'Run okx auth login first', 'Session expired', 'not authenticated', 'requires_auth', '401 Unauthorized', 'token expired/not found', 'StorageNotFoundError', '会话过期', '未认证', '需要登录'. Also when the user asks about login status or the login was interrupted. Also when the user wants to install/update/check/remove the okx-auth binary — 'install/update/remove auth', 'download okx-auth', '安装/更新/卸载认证', 'auth binary status', 'Failed to spawn okx-auth'. Also use before using okx-cex-trade/portfolio/earn/bot for the first time. Do NOT use for market data queries (use okx-cex-market)."
license: MIT
metadata:
  author: okx
  version: "1.4.9"
  homepage: "https://www.okx.com"
  agent:
    requires:
      bins: ["okx"]
    install:
      - id: npm
        kind: node
        package: "@okx_ai/okx-trade-cli@1.4.9"
        bins: ["okx"]
        label: "Install okx CLI (npm)"
---

# OKX CEX Authentication

OAuth 2.0 device flow authentication for OKX CLI. Guides first-time setup, re-authentication after session expiry, and logout.

## Supported Sites

| Site | Region | URL |
| -------- | ----------------------- | --------------- |
| `global` | Global | `www.okx.com` |
| `eea`    | EEA    | `my.okx.com`  |
| `us`     | US     | `app.okx.com` |
| `tr`     | TR     | `tr.okx.com`  |

Site is a separate dimension from auth method. Both API-key and OAuth paths require a site. Once selected, a site is persisted:
- **API-key users**: `profile.site` in `~/.okx/config.toml` (written by `okx config init`).
- **OAuth users**: saved inside the `okx-auth` binary state the first time `okx auth login --site <X>` succeeds, and returned by `okx auth status --json` as the `site` field.

There is **no `okx config set-site` command** — site cannot be persisted independently of an auth attempt. For OAuth flows, the agent must remember the user's choice within the conversation and pass `--site <X>` on `okx auth login`.

## Prerequisites

Install `okx` CLI if not already installed:

```bash
npm install -g @okx_ai/okx-trade-cli
```

## Step 0: Pre-flight Check (MANDATORY)

**Unconditional rule — do NOT skip Step 0 under any circumstances.** Even if a prior skill (preflight, okx-cex-portfolio, etc.) already ran `auth status` and passed you a conclusion like "user is not_logged_in, go log in" — **you MUST re-run the two commands below yourself and walk Steps 0.1 → 0.2 → 0.3 in order**. Upstream tool output does not substitute for your own pre-flight. The single most common failure mode for this skill is an agent that reads an upstream "not authenticated" signal, skips Step 0.1 site selection, and calls `okx auth login` with a silently-defaulted site.

Run both in parallel:

```bash
okx config show --json
okx auth status --json
```

Then apply the following three checks **in strict order** — each step short-circuits the rest.

### Step 0.1 — Site check (independent of auth mode)

A site is considered already selected if **either** is true:
````
END THIRD-PARTY FILE 58a186334bc978c7

The third-party file has ended. Everything between the 58a186334bc978c7 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 3326 of 18413 bytes. © okx · MIT · https://github.com/okx/agent-skills/tree/HEAD/skills/okx-cex-auth/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md