OKX API 키 연결 방법과 오류 50119 해결법

OKX API 키가 유효해도 “API 키가 존재하지 않습니다.”라는 응답이 나올 수 있다. EEA 키가 OKX Europe의 인프라 대신 글로벌 API로 전송된다면 키를 다시 만들어도 문제가 해결되지 않는다. 내가 OKX API 키를 연결하고, 올바른 계정 지역을 선택하고, 인증 정보를 바꾸기 전에 오류를 진단하는 방법을 보여주겠다.

핵심은 인증 정보와 지역별 엔드포인트의 조합을 확인하는 것이다. 정확히 복사한 키라도 잘못된 지역 호스트로 전송하면 권한을 확인하는 단계에 도달하기 전에 실패할 수 있다.

유효한 OKX API 키도 잘못된 지역별 엔드포인트에서는 실패할 수 있다

연결에 실패하면 다른 키를 생성하고, 다시 붙여 넣고, 권한을 더 부여하고 싶어진다. 하지만 이런 접근은 모든 인증 실패를 인증 정보의 문제로 취급한다.

OKX의 지역별 구조에서는 그 가정을 믿을 수 없다.

OKX Europe Limited는 Malta의 MFSA를 통해 인가받은 별도의 MiCA 규제 대상 법인이다. EEA 계정은 my.okx.com에 속하며, 해당 API 키는 OKX Europe의 API 인프라에서만 유효하다.

완전히 유효한 EEA 키를 글로벌 www.okx.com API로 전송해도 50119: “API 키가 존재하지 않습니다.”라는 응답이 나올 수 있다. 키는 존재하지만, 요청이 잘못된 지역별 엔드포인트에 도달한 것이다.

US 계정에는 별도의 지역 호스트인 us.okx.com이 있다. 이 계정의 연결에도 해당 지역 인프라가 필요하다.

브라질 OKX 계정은 글로벌 플랫폼과 동일한 API를 사용하므로 Global을 선택해야 한다. 현지 시장에서 운영한다고 해서 별도의 API 지역이 있다는 뜻은 아니다.

나는 여기서부터 문제를 진단한다. 패스프레이즈를 바꾸거나 권한을 늘려도 지역 불일치는 바로잡을 수 없기 때문이다. 요청은 해당 키를 인식하는 인프라에 도달해야 한다.

필요한 권한으로 OKX API 키를 생성하는 방법

연결에는 의도한 작업을 수행하는 데 필요한 접근 권한을 부여해야 한다. 오류를 없애려고 권한을 추가하는 것은 잘못된 진단 방법이다.

포트폴리오 조회에는 Read를 사용하자. 주문을 실행하는 봇을 사용할 때만 Trade를 추가하자.

이 연결에서는 절대로 Withdrawal을 활성화하지 말자.

OKX API 키 설정 단계

1. OKX 계정에서 API 관리를 연다.

연결하려는 계정에 로그인하고 API 관리 영역으로 이동하자. 키를 생성하기 전에 해당 계정이 Global, EEA, US 중 어디에 속하는지 확인하자.

1. 이 연결 전용 API 키를 생성한다.

나중에 접근 권한을 검토할 때 용도를 알아볼 수 있도록 식별하기 쉬운 이름을 지정하자. 전용 키를 사용하면 이 연결의 접근 권한만 별도로 변경하거나 철회하기도 쉽다.

1. 생성 과정에서 API 패스프레이즈를 설정한다.

API 키에 사용할 패스프레이즈를 직접 정하는 단계다. 이것은 OKX 계정 비밀번호가 아니며, 연결할 때 API 키 및 시크릿과 함께 필요하다.

1. 포트폴리오 조회를 위해 Read를 활성화한다.

포트폴리오 정보를 확인하는 것이 목적이라면 Read 권한으로 시작하자. 조회 전용 연결에는 거래 권한이 필요하지 않다.

1. 주문을 실행해야 하는 봇에만 Trade를 추가한다.

Trade 권한은 거래 활동을 허용한다. 인증 오류를 해결하기 위한 실험이 아니라, 그 목적에 맞게 의도적으로 활성화하자.

1. Withdrawal은 비활성화 상태로 둔다.

포트폴리오 조회와 봇의 주문 실행에는 출금 권한이 필요하지 않다. 이 설정을 완료하기 위해 출금 권한을 부여하지 말자. 출금을 비활성화해도 거래 손실까지 막을 수는 없다는 점을 기억하자. Trade 권한이 있는 키는 손실을 내는 주문도 실행할 수 있으므로, 거래 연결이 접근할 수 있는 계정에 보유하는 자금을 제한하자.

1. 가능한 경우 키를 연결에 사용하는 IP 주소에 바인딩한다.

API 요청을 보내는 서비스가 지정한 IP 주소를 사용하자. 실제 사용하는 연결에 맞게 이 설정을 유지하자.

1. API 키, 시크릿, 패스프레이즈를 안전하게 보관한다.

모두 인증 정보로 취급하자. 연결 양식에 입력할 때는 각 값이 빠짐없이 입력됐는지, 모두 동일한 API 키에 속하는지 확인하자.

키 생성은 설정의 일부일 뿐이다. 연결을 처리하는 쪽에서도 어떤 지역 호스트를 사용해야 하는지 알아야 한다.

IP 화이트리스트가 중요한 이유

IP 바인딩은 키를 사용할 수 있는 위치를 제한한다. 키의 유지 여부에도 영향을 준다. OKX는 IP 바인딩이 없는 비활성 API 키를 삭제할 수 있으므로, 생성한 뒤 사용하지 않은 키는 나중에 다시 사용하려 할 때 이미 존재하지 않을 수 있다.

인증 정보를 저장해 두었다고 해서 키가 계속 활성 상태라고 가정하지 말자. OKX API 관리에서 상태를 확인하자.

별도로 주의해야 할 설정 문제도 있다. 활성 키라도 요청자의 IP가 화이트리스트에 없으면 요청을 거부할 수 있다. 이 경우에는 IP 관련 오류가 발생하므로, 키를 다시 생성할 것이 아니라 IP 설정을 확인해야 한다.

유효한 키인데도 OKX가 “API 키가 존재하지 않습니다”라고 응답하는 이유

이 문구는 단정적으로 들린다. 하지만 진단에서 이 문구가 의미하는 범위는 겉으로 보이는 것보다 좁다.

EEA 계정에서 오류 50119는 OKX Europe의 인프라에서는 유효한 키를 글로벌 엔드포인트가 인식하지 못한다는 뜻일 수 있다. 연결 안내에서 계정이 어느 법인에 속하는지 전혀 묻지 않는다면, 이 경우를 드러낼 수 없다.

지역별 분리는 인증 정보에 관한 추측이 아니라 문서화된 사실이다

OKX EEA API FAQ에는 my.okx.com의 지역별 사용 맥락과 EEA 키가 해당 지역에서만 유효하다는 내용이 명시돼 있다. Freqtrade, CCXT, Hummingbot의 공개 이슈 보고에서도 연동에 글로벌 호스트를 사용한 EEA 사용자에게 “API 키가 존재하지 않습니다”라는 응답이 나타나는 패턴을 확인할 수 있다.

이 보고들은 지역별 엔드포인트를 확인해야 한다는 근거가 된다. 모든 발생 사례의 원인이 같다는 증거는 아니다.

내 진단 결론은 명확하다. OKX에서 여전히 활성 상태로 표시되는 키를 교체하기 전에 계정 지역을 확인하자. 커넥터가 모든 계정이 글로벌 API를 사용한다고 가정한다면, 키를 반복해서 생성해도 그 가정은 그대로 남는다.

오류 50119의 다른 원인도 확인해야 한다

지역 불일치만이 유일한 설명은 아니다. 같은 오류는 다음과 같은 경우에도 발생할 수 있다.

• 데모 거래 키를 잘못된 환경에서 사용한 경우. 인증 정보가 연결에서 요구하는 환경과 일치하는지 확인하자.
• 키가 자동으로 삭제된 경우. OKX API 관리에서 키가 여전히 존재하는지 확인하자.
• 붙여 넣은 값이 잘린 경우. API 키 전체가 입력됐는지 확인하자.
• 실제로 인식할 수 없는 키인 경우. 인증 정보가 연결하려는 계정에서 발급된 것인지 확인하자.

나는 모든 것을 한꺼번에 바꾸는 대신 이런 가능성을 순서대로 확인한다. 인증 정보, 권한, 환경, 지역을 동시에 바꾸면 재시도에 성공해도 무엇이 잘못됐는지 거의 알 수 없다.

유용한 질문은 이것이다. 이 엔드포인트는 이 계정과 환경에서 이 활성 키를 인식하는가?

재시도하기 전에 OKX 오류 코드를 해석하자

연결 실패는 증상이다. OKX 오류 코드는 그보다 유용한 증거다.

공개된 OKX API 오류 코드 문서는 알 수 없는 키, 잘못된 패스프레이즈, 유효하지 않은 서명, IP 제한을 구분한다. 각각 연결의 다른 부분을 가리킨다.

오류 코드	의미	확인할 사항
50119	API 키가 존재하지 않음	계정 지역과 지역 호스트, 데모 환경과 의도한 환경의 일치 여부, 키 삭제 여부, 붙여 넣은 키의 완전성
50105	잘못된 API 패스프레이즈	계정 비밀번호가 아니라 해당 API 키를 생성할 때 설정한 패스프레이즈 사용
50113	유효하지 않은 서명	API 시크릿과 연동의 요청 서명 구현 확인
50110	요청 IP가 화이트리스트에 없음	요청자의 IP가 키의 허용 IP 설정에 포함됐는지 확인

오류 50105: API 패스프레이즈를 확인하자

API 패스프레이즈는 별도의 인증 정보다. 해당 필드에 OKX 로그인 비밀번호를 입력해도 인증 요건을 충족하지 못한다.

패스프레이즈가 API 키 및 시크릿과 동일한 키에 속하는지도 확인하자. 서로 다른 생성 시도의 인증 정보를 섞으면 각 값은 그럴듯해 보여도 서로 맞지 않는 조합이 될 수 있다.

오류 50113: 요청 서명을 조사하자

유효하지 않은 서명 오류는 요청에 포함된 인증 서명을 가리킨다. API 시크릿을 확인하고, 직접 연동을 유지·관리한다면 서명 구현도 확인하자.

연결 양식을 사용한다면 요청 서명을 조사하기 위해 커넥터의 지원 창구나 기술 문서를 참고하자. Trade나 Withdrawal을 활성화해도 유효하지 않은 서명은 해결되지 않는다.

오류 50110: IP 화이트리스트를 점검하자

이 오류는 허용 IP 설정을 확인하라는 뜻이다. 요청을 보내는 서비스가 사용하는 IP를 확인한 뒤 키의 화이트리스트와 비교하자.

같은 요청을 무작정 재시도하면 불일치는 그대로 남는다. 다시 테스트하기 전에 해당 설정을 바로잡자.

OKX를 Anny에 연결하는 방법

내 연결 양식에는 Global, EEA, US 옵션을 제공하는 계정 지역 선택 항목이 있다. 이 선택에 따라 적절한 지역 호스트에서 키를 검증한다.

연결 과정은 다음과 같다.

1. 거래소 추가 양식을 열고 OKX를 선택한다.

API 키, 시크릿, API 패스프레이즈를 준비하자.

1. 계정 지역을 선택한다.

OKX Europe 계정은 EEA, OKX US 계정은 US, 글로벌 플랫폼의 계정은 Global을 선택하자. 브라질 계정은 Global을 선택한다.

1. 서로 일치하는 인증 정보를 입력한다.

API 키와 시크릿 전체를 붙여 넣은 다음, 키를 생성할 때 설정한 패스프레이즈를 입력하자.

1. 권한이 목적에 맞는지 확인한다.

포트폴리오 조회에는 Read를 사용하자. Trade는 봇에만 추가하고 Withdrawal은 비활성화 상태로 두자.

1. 연결을 검증한다.

실패하면 반환된 오류 코드를 기준으로 다음에 확인할 항목을 정하자. 50119라면 다른 키를 생성하기 전에 지역을 다시 확인하자.

OKX를 Anny에 연결하기

지역 선택은 표시 환경설정이 아니라 인증 요건이다. 인증 정보를 어디에서 확인할지 결정한다.

문제 해결에 OKX API 문서를 활용하는 방법

기존 양식으로 연결한다면 지역 선택 항목과 오류 표가 실질적인 출발점이다. 연동을 직접 유지·관리한다면 인증 문서와 함께 지역별 안내를 읽자.

OKX API 문서의 관련 항목은 서로 다른 질문에 답한다.

• 지역별 API 안내: 이 계정의 요청은 어느 인프라로 보내야 하는가?
• 인증 안내: 어떤 인증 정보가 필요하며, 요청에 어떻게 서명해야 하는가?
• 오류 코드 참조 문서: 제출한 요청의 어느 부분이 거부됐는가?

서명 구현이 올바르더라도 잘못된 지역 호스트로 요청을 보낼 수 있다. 지역 호스트가 올바르더라도 잘못된 패스프레이즈는 거부될 수 있다.

나는 이 항목들을 따로 확인한다. 각각 바로잡아야 할 부분이 다르기 때문이다. 연결에 성공하려면 엔드포인트, 인증 정보, 환경, 권한, IP 설정이 서로 맞아야 한다.

OKX API 연결에 관한 자주 묻는 질문

OKX API 키에도 만료가 있는가?

API 키를 무기한 사용할 수 있다고 가정하지 말자. OKX는 IP 바인딩이 없는 비활성 키를 삭제할 수 있으므로, 이전에 저장한 인증 정보가 작동하지 않으면 API 관리를 확인하자.

가능한 경우 연결에 지정된 IP 주소에 키를 바인딩하고, 패스프레이즈나 권한 문제를 조사하기 전에 키가 여전히 활성 상태인지 확인하자.

유효한 OKX API 키인데 왜 존재하지 않는다고 하는가?

유효한 키도 잘못된 지역별 엔드포인트로 전송하면 50119가 반환될 수 있다. 특히 EEA 키는 OKX Europe의 인프라에서 사용해야 한다. 글로벌 www.okx.com API로 전송하면 “API 키가 존재하지 않습니다”라는 응답이 나올 수 있다.

데모 환경 불일치, 키 자동 삭제, 불완전한 붙여 넣기도 확인하자.

OKX 거래 봇에는 어떤 권한이 필요한가?

포트폴리오 조회에는 Read를 사용하고, 봇이 주문을 실행해야 할 때 Trade를 추가하자. 이 연결에서는 절대로 Withdrawal을 활성화하지 말자.

권한을 추가해도 지역 불일치, 잘못된 패스프레이즈, 유효하지 않은 서명, IP 화이트리스트 오류는 해결되지 않는다.

OKX API 패스프레이즈는 내 비밀번호와 같은가?

아니다. API 패스프레이즈는 API 키를 생성할 때 설정하며, OKX 계정 비밀번호와 별개다.

해당 키에 연결된 패스프레이즈를 입력하자.

브라질 OKX 계정은 어떤 지역을 선택해야 하는가?

Global을 선택하자. OKX Brazil은 글로벌 플랫폼에서 운영되며 동일한 API를 사용한다.

연결에 실패할 때마다 새 키를 생성해야 하는가?

아니다. 먼저 오류 코드를 읽고 해당 코드가 가리키는 설정을 확인하자.

50119라면 지역 호스트, 환경, 키의 활성 상태, 붙여 넣은 값의 완전성을 확인하자. 키를 계속 잘못된 지역별 엔드포인트로 보내는 연결은 새 키로도 고칠 수 없다.

다음에 할 유용한 행동은 똑같은 재시도가 아니라 진단이다. 지역부터 확인하고, 코드를 읽고, 증거가 가리키는 설정을 바꾸자.

이 글은 교육 목적이며 금융 조언이 아니다. 과거 성과 ≠ 미래 결과. Anny는 AI 기반 분석 플랫폼이며, 등록된 투자자문사가 아니다.