전략 API (ctx)

전략은 자바스크립트 함수 하나입니다. 백테스트와 라이브가 완전히 같은 인터페이스를 씁니다 — 한쪽에만 있는 기능은 없습니다.

function onUpdate(ctx) {
  // 봉마다(백테스트) / 갱신마다(라이브) 호출됩니다
  // null, 주문 객체 하나, 또는 주문 객체 배열을 반환하세요
}

무엇을 만들 수 있나요

• 시장: 암호화폐 현물(업비트·바이낸스 등 연동 거래소), 무기한 선물(바이낸스 USDT-M·COIN-M 등 — 레버리지, 롱/숏, 격리/교차 마진), 한국 주식(증권사 오픈API — 한국 주식 거래 시작하기), 미국·해외 주식(IBKR — 실기기 확인 전), 외환·CFD(MetaTrader 5 — 실거래 경로 진행 중). 시장마다 백테스트·모의·실거래 범위가 다릅니다.
• 선물 거래소 실거래: 일부 파생 거래소는 실거래 전에 키 화면의 [연결 시험](소액 주문 왕복)을 거칩니다. 내 계정으로 시험을 통과하면 그 즉시 그 거래소에서 실거래·자동 실행을 쓸 수 있습니다(키를 바꾸면 다시 시험). API 가 거래와 출금을 분리하지 못하는 거래소는 경고를 읽고 직접 동의해야 키가 등록되고, 시드 문구는 받지 않습니다 — 자세한 건 보안.
• 다종목 스캐너: 한 전략이 같은 거래소의 여러 종목(최대 200개)을 동시에 봅니다 — 종목별 포지션·주문·상태 자동 분리.
• 한 전략에서 두 거래소에 동시 주문(legs — 거래소 간 차익거래·헷지): 백테스트(잡 포함)·페이퍼·라이브 실주문까지 지원합니다. 다리별 지갑·수수료·킬스위치 연동, 라이브는 모든 다리의 API 키가 있어야 시작합니다(한 다리만 실행되는 반쪽 헷지 방지 — 조용한 강등 없음). 통화가 다른 다리의 손익은 합산하지 않습니다(참고용 근사 USD 만 표기).
• 보조 종목 참조: 다른 종목·다른 거래소의 시세를 신호로 씁니다(ctx.ref 슬롯 — 예: 바이낸스 BTC 를 보며 업비트에서 거래). 백테스트·모의·실거래 모두 지원.
• 여러 거래소 동시 운용: 거래소마다 실행을 따로 띄워도 됩니다 — 에이전트 하나가 여러 거래소 키를 보유하고 전부 병렬로 돌립니다(업비트 A전략 + 바이낸스 선물 B전략).
• 멀티 에이전트 클러스터: 스캐너 종목을 여러 에이전트에 자동 분배해 병렬 실행합니다(엘리트 플랜 + 온보딩 후 활성화).
• 데이터: 캔들(1분~1일)·거래량·호가·펀딩비·미결제약정(OI)/청산 + 기본 지표(미 국채 금리·달러·VIX·유가 등 — 에이전트가 모아 ctx.data('base.이름') 로) + 내 DB(전략 코드의 DATA 선언 — 접속 정보는 에이전트에만) + 외부 신호(웹훅·폴링 — ctx.signal, 외부 신호). 모르는 값은 null — 0 으로 위조하지 않습니다.
• 환율(김프용 USD/KRW · 원화↔USDT 환산): 기본 제공 환율이 없습니다 — 서버가 환율을 더 이상 수집하지 않습니다. 직접 가져옵니다: 가장 쉬운 길은 웹훅 신호 ctx.signal — 예: TradingView 1분봉 USDKRW 알림(봉 마감마다)을 /api/hooks/t/<토큰>?slot=usdkrw 로, 본문 {"rate": {{close}}, "t": "{{timenow}}"} → 전략에서 const s = ctx.signal('usdkrw'); const rate = s && Number(s.payload.rate), 나이(s.age, 초)로 오래된 값을 거릅니다(서버 한도 슬롯당 분당 12건). 백테스트에는 보내기 시작한 뒤의 기록만 as-of 로 보입니다. 그 밖에 실거래·모의는 ctx.http(환율 제공사 주소를 선언하고 실행에서 승인), 백테스트까지 쓰려면 ctx.data(DATA 에 내 환율 표, 또는 약 10일 늦게 발표되는 일별 base.usdkrw_h10). 환율이 없으면 null = 김프 없음. 예전 ctx.fx 는 저장된 전략이 멈추지 않게 남겨 둔 것이라 항상 null 입니다.
• 주문: 시장가·지정가·분할 진입, 라이브 전용 스마트 주문(추격·트리거).
• 안전장치: 지갑(최대 손실 = 지갑), 주문 속도 제한·승인 천장, dry-run. (기준액 없이 배포된 옛 실거래 실행·legs 는 예전 손실 킬스위치가 그대로 걸립니다.)
• 검증: 최대 10만 봉 백테스트, 종료일 고정으로 여러 구간 검증(walk-forward) + 스튜디오 틱 판단시간 예측·라이브 틱 실측 모니터(서버가 일 잘하나 실행 카드에서 확인).

아직 안 되는 것 (지원하는 척하지 않습니다):

• 다리별 분산 실행(legs 를 여러 에이전트에)의 실거래 — 분산 실행(계산 에이전트 + 다리별 집행 에이전트)은 페이퍼에서만 됩니다. 실주문은 두 기기 실측 뒤에 엽니다. 실거래 legs 는 지금 한 에이전트가 모든 다리 키를 갖고 실행합니다.
• 클러스터 자동 재배분 — 분배는 정적입니다. 에이전트가 이탈하면 그 종목들은 대기하며 화면에 정직하게 표시됩니다(몰래 다른 에이전트로 옮기지 않음).
• 일부 국내 증권사의 실계좌 검증 — 실계좌로 주문·체결 왕복을 아직 확인하지 못한 증권사: LS증권, NH투자증권 나무 PLUG, NH투자증권 N2 PLUG, 토스증권. 배포 때 '미검증 경고'로 이유를 알려줍니다. 틀리면 증권사 오류 코드가 그대로 표시됩니다. 처음엔 소액으로 확인하세요.

규칙

• 순수 함수 — 네트워크·import·async 금지. 아래 ctx 만 사용합니다.
• qty 는 언제나 코인 수량입니다(현금 아님).
• 지표는 데이터가 모자라면 null — 반드시 null 검사를 하세요.
• 내 변수는 ctx.state 에 보관하면 호출 간 유지됩니다.
• ctx.ref 슬롯은 논리명('hedge' 등)으로 — 실제 종목은 배포 때 연결됩니다.
• ctx 기능이 있는지 검사하는 코드(typeof ctx.watch === 'function' 등)는 쓰지 마세요. 전략이 쓰는 기능을 에이전트가 지원하는지는 배포할 때 플랫폼이 확인하고, 부족하면 필요한 버전을 알려주며 배포를 막습니다.
• ctx.watch 는 차트·실행 카드에 대기 가격을 표시만 합니다 — 주문이 아닙니다. 주문은 onUpdate 의 반환값뿐입니다.
• 가격 말고 다른 조건(RSI 등)도 있으면 선언에 conds 로 함께 넣으세요 — 판단에 쓴 그 값(같은 기간·같은 봉)으로: conds: [{ label: 'RSI(14) 마감', now: rsi, op: '<', ref: 30, closed: true }]. 하나라도 거짓이면 실행 카드가 "조건 대기"로 보여 주고 도달 추정을 숨깁니다.

주문 객체

• 시장가: { side: 'buy'|'sell', qty } — 호가를 타고 체결(슬리피지·부분체결·taker 수수료).
• 지정가: { side, qty, type: 'limit', price } — 가격이 닿으면 maker 수수료로 체결. postOnly: true 면 즉시 체결될 지정가는 거부.
• 스마트(작업 주문): { side, qty, type: 'smart', chase?, slices?, trigger?, hardStopMs? } — 시간에 걸쳐 집행합니다. 체이싱(호가 추격→마감 시 크로스)·분할·스톱/트레일링 트리거·강제 마감을 조합할 수 있고, 라이브·페이퍼에서 집행됩니다. 백테스트는 시장가로 근사하니 라이브 페이퍼로 검증하세요.
• 지정가 사다리: { book: [{ key, side, qty, price | at: 'top' }], tol?, refreshMs? } — '걸려 있어야 할 지정가 목록'을 매 틱 그대로 내면 됩니다. 이미 걸린 것과 맞춰 허용 한도 안이면 그대로(재주문 없음), 밖이면 고치고, 빠진 key 는 취소합니다. 한도 = max(0.05%, 현재가와의 거리 × 0.2) — 가까운 주문은 조이고 먼 주문은 넉넉히, 가까운 것부터 처리합니다. 기본은 메이커 전용(postOnly). at: 'top' 은 매수 최고가+1틱(체결될 자리면 최고가). refreshMs 를 주면 한도 안이어도 그 시간마다 1틱 이상 다를 때 고칩니다(실거래는 유량 여유가 있을 때만). 체결된 key 는 한 번 뺐다가 다시 내야 또 겁니다. 백테스트는 틱이 없어 맨 위를 최고가에 줄세웁니다(결과에 표시).
• 전체 취소: { cancel: 'all' } — 대기 지정가와 작업 주문 전부 취소(체이싱은 개별 주문 취소로 못 멈춥니다).

밖으로 보내기 (ctx.http) — 알림·외부 API

전략이 텔레그램·디스코드·슬랙 알림이나 외부 API 를 부를 수 있습니다(에이전트 1.348.0 이상). 키는 코드에 넣지 않습니다 — 에이전트의 HTTP 보관소에 두고, 코드는 자리 이름만 씁니다.

const HTTP = { origins: ['https://api.telegram.org'], creds: { tg: 'https://api.telegram.org' } };
function onUpdate(ctx) {
  if (ctx.close > 100000) ctx.http.send({ id: 'alert', cred: 'tg', path: '/sendMessage', method: 'POST', json: { chat_id: 1, text: 'BTC > 100k' } });
  return null;
}

• HTTP 선언에 없는 주소로는 안 나갑니다. run 마다 에이전트 화면에서 자리 ↔ 보관소 항목을 직접 승인해야 보내집니다(선언이나 코드가 바뀌면 다시 승인).
• 보관소는 등록할 때 도메인을 크게 보여주고, 닮은 도메인(te1egram.org 등)·처음 보는 도메인은 도메인을 다시 입력해야 저장됩니다. 키는 지정한 출처로만 붙고 응답에서 지워집니다.
• 틱당 5건·응답 64KB·리다이렉트 안 따라감·사설 IP 차단. 결과는 다음 틱에 ctx.http.result(id).
• 백테스트는 보내지 않습니다 — 결과의 httpNotSent 에 건수만 남습니다.
• 코드에 키 모양 문자열이 있으면 저장 때 경고하고, AI 에게는 자리표시자로 가려서 보여주며, git 공개 발행에서 그 전략은 빠집니다.

아래 표가 ctx 의 전부입니다(자동완성과 같은 출처에서 생성). AI 에게 전략 코드를 받으려면 AI 전략 만들기를 쓰거나, AI 문서를 통째로 붙여넣으세요.