에이전트 키

세 가지 작업으로 이루어진 에이전트 키 등록 및 관리.

에이전트는 메인 지갑을 노출하지 않고 사용자를 대신해 거래 요청에 서명할 수 있는 Ethereum 기반 키 쌍입니다. 에이전트의 주소는 소유 지갑의 서명으로 승인받아 한 번 등록합니다. 그 이후에는 에이전트 키가 거래 권한을 가지며, 지갑 키는 오프라인에 둡니다.

이 섹션의 어떤 작업에도 세션 토큰이 필요하지 않습니다. 요청 본문에 담긴 EIP-712 서명이 등록을 요청 안에서(in-band) 승인하므로, 등록에는 자격 증명이 전혀 필요하지 않습니다. 두 가지 관리 작업(GET /agents, DELETE /agents/{address})은 HMAC API 키로 인증합니다.

작업

승인 방식

POST /agents/register

요청 본문의 EIP-712 서명. 세션 토큰도, API 키도 필요하지 않습니다.

GET /agents

hmacAuth

DELETE /agents/{address}

hmacAuth

아래 모든 예시의 기본 URL은 퍼블릭 테스트넷 기본 경로인 https://api.testnet.nexus.xyz/v1입니다.

EIP-712 페이로드

에이전트를 소유할 지갑의 타입 데이터(typed-data) 서명이 등록을 승인합니다.

도메인

{
  "name": "Nexus Exchange",
  "version": "1",
  "chainId": "<testnet chain id>",
  "salt": "<network salt, see below>"
}

타입

RegisterAgent {
  address agent
  uint64  expiresAt
  uint64  nonce
}

중요한 세부 사항:

서명은 agent, expiresAt, nonce의 세 개 필드를 대상으로 합니다. 소유 wallet은 타입 데이터에 포함되지 않습니다. 지갑 주소는 요청 본문에 함께 보내며, 서버는 복원된 서명자가 이 주소와 일치하는지 확인합니다.
타입 데이터 필드 이름은 camelCase(expiresAt)이고, JSON 요청 본문은 snake_case(expires_at)를 사용합니다. camelCase 이름으로 서명하고, snake_case 이름으로 보내십시오.
expires_at을 서버 측 기본값에 맡기면 서명할 값이 없습니다. 만료 시각을 직접 계산해 서명하고, 명시적으로 보내십시오.
계약은 도메인의 chainId를 자리표시자 <testnet chain id>로 적을 뿐 값을 고정하지 않습니다. 체인 ID의 기준은 배포 환경입니다. 해당 게이트웨이의 GET /metadata에서 읽으십시오(네트워크 참조). 도메인이 일치하지 않으면 설명적인 오류가 아니라 signer_mismatch가 발생하므로, 서명하기 전에 대상 게이트웨이가 기대하는 값을 확인하십시오.
도메인에는 salt도 포함됩니다. 값은 keccak256(<network>)이며, 여기서 <network>는 서명 대상 게이트웨이의 소문자 배포 이름("mainnet", "testnet" 또는 "local")입니다. 이 값은 RegisterAgent 서명을 하나의 배포 환경으로 한정합니다. chainId가 우연히 일치하더라도 같은 서명은 다른 네트워크에서 유효하지 않습니다. 잘못된 salt는 다른 신호 없이 signer_mismatch만 발생시키므로, 직접 다시 계산하지 말고 대상 배포 환경의 salt 값을 조회하십시오.

`POST /agents/register`

에이전트 키를 등록합니다.

지갑에 새 에이전트 키를 등록합니다. 에이전트는 메인 지갑을 노출하지 않고 사용자를 대신해 거래 요청에 서명할 수 있는 Ethereum 기반 키 쌍입니다. 에이전트를 소유할 지갑의 EIP-712 서명이 등록을 승인합니다. 세션 토큰은 필요하지 않습니다.

EIP-712 도메인: { name: 'Nexus Exchange', version: '1', chainId: <testnet chain id>, salt: <network salt> }. 타입 데이터 타입: RegisterAgent { address agent, uint64 expiresAt, uint64 nonce }.

인증: 없음. 요청에 담긴 EIP-712 서명으로 요청 자체를 승인합니다.

요청 본문

AgentRegistrationRequest, application/json, 필수.

필드

타입

필수

설명

wallet

string

예

소유자 지갑 주소(0x 접두사, 20바이트)

agent

string

예

에이전트 키 쌍에서 도출한 에이전트 Ethereum 주소(0x 접두사, 20바이트)

expires_at

integer (int64)

아니요

Unix ms 단위의 만료 시각. 선택 사항이며 기본값은 now+30 d입니다. [now+1d, now+90d] 범위여야 합니다.

nonce

integer (int64)

예

단조 증가 논스. 안전한 시작값으로 현재 Unix 타임스탬프(ms)를 사용하십시오.

signature

string

예

지갑 개인 키로 RegisterAgent{agent, expiresAt, nonce}에 서명한 EIP-712 서명(0x 접두사)

label

string

아니요

사람이 읽을 수 있는 에이전트 레이블(선택 사항, 예: my-bot)

응답

`200`

에이전트가 등록되었습니다. 계약은 이 응답에 예시를 제공하지만 이름 있는 스키마는 제공하지 않습니다.

필드

타입

설명

agent_address

string

등록된 에이전트 주소(0x 접두사)

expires_at

integer (int64)

적용된 만료 시각, Unix ms. 보낸 값, 또는 생략했다면 서버 기본값

`400`

잘못된 요청: bad_wallet, bad_agent, expiry_out_of_range(현재부터 [1 d, 90 d]), 또는 invalid_json.

`401`

signature_invalid 또는 signer_mismatch. EIP-712 서명이 주장된 지갑으로 복원되지 않았습니다.

`409`

duplicate_agent. 해당 에이전트 주소는 이미 이 지갑에 등록되어 있습니다.

예시

curl -X POST 'https://api.testnet.nexus.xyz/v1/agents/register' \
  -H 'Content-Type: application/json' \
  -d '{
    "wallet": "0xAbCdEf0123456789AbCdEf0123456789AbCdEf01",
    "agent": "0x1234567890AbCdEf1234567890AbCdEf12345678",
    "expires_at": 1782000000000,
    "nonce": 1,
    "signature": "0xdeadbeef..."
  }'

응답:

{
  "agent_address": "0x1234567890AbCdEf1234567890AbCdEf12345678",
  "expires_at": 1782000000000
}

`GET /agents`

에이전트 목록을 조회합니다.

인증된 지갑에 등록된 만료되지 않은 모든 에이전트 키를 반환합니다. 서버는 만료된 에이전트를 걸러 내므로, 이 목록에서 사라진 에이전트는 수명 주기가 끝난 것입니다. 오류가 아닙니다.

인증: hmacAuth(HMAC API 키).

응답

`200`

에이전트 레코드 배열. 각 항목은 AgentInfo입니다.

필드

타입

설명

address

string

에이전트 주소(0x 접두사)

expiresAt

integer (int64)

만료 시각, Unix ms

registeredAt

integer (int64)

등록 시각, Unix ms

label

string | null

선택적 레이블

snake_case인 등록 요청 본문과 달리, 여기의 응답 필드 이름은 camelCase입니다.

`401`

HMAC 인증이 필요합니다.

예시

curl 'https://api.testnet.nexus.xyz/v1/agents' \
  -H "X-API-Key: nx_a1b2c3d4e5f67890" \
  -H "X-Timestamp: $TIMESTAMP" \
  -H "X-Signature: $SIGNATURE"

응답:

[
  {
    "address": "0x1234567890AbCdEf1234567890AbCdEf12345678",
    "expiresAt": 1782000000000,
    "registeredAt": 1779000000000,
    "label": "my-bot"
  }
]

X-Timestamp와 X-Signature를 만드는 방법은 인증을 참조하십시오.

`DELETE /agents/{address}`

에이전트 권한을 해제합니다.

에이전트 키의 권한을 즉시 해제합니다. 이 호출이 반환된 후, 서버는 권한이 해제된 에이전트가 서명한 처리 중인 요청을 모두 거부합니다.

인증: hmacAuth(HMAC API 키).

파라미터

이름

위치

타입

필수

설명

address

path

string

예

권한을 해제할 에이전트 주소(0x 접두사)

응답

`200`

에이전트 권한이 해제되었습니다.

`401`

HMAC 인증이 필요합니다.

`404`

에이전트를 찾을 수 없거나 사용자 소유가 아닙니다. 소유권 확인 실패는 403이 아니라 404를 반환하므로, 다른 지갑의 에이전트를 탐색할 수 없습니다.

예시

curl -X DELETE 'https://api.testnet.nexus.xyz/v1/agents/0x1234567890AbCdEf1234567890AbCdEf12345678' \
  -H "X-API-Key: nx_a1b2c3d4e5f67890" \
  -H "X-Timestamp: $TIMESTAMP" \
  -H "X-Signature: $SIGNATURE"

운영 참고 사항

만료 기한에는 범위 제한이 있습니다. 에이전트는 등록 후 1일에서 90일 사이에 만료되어야 하며, expires_at을 생략하면 30일이 적용됩니다. 사양 0.9.90 기준으로 갱신 작업이 없으므로, 기존 에이전트가 만료되기 전에 새 에이전트를 다시 등록하십시오.
논스는 지갑별로 단조 증가합니다. 현재 Unix 밀리초 타임스탬프를 논스로 사용하면 상태를 추적하지 않고도 이 순서 조건을 충족합니다.
권한 해제는 즉시 적용되며, 처리 중인 요청에도 적용됩니다. DELETE가 반환되면 서버는 권한이 해제된 에이전트가 서명한 요청을 거부합니다.
등록은 전송 계층에서 인증되지 않습니다. 누구나 등록을 제출할 수 있지만, 서버는 주장된 지갑의 유효한 EIP-712 서명만 받아들입니다. RegisterAgent에 대한 서명은 최대 90일 동안 거래 권한을 부여하므로 지갑 키를 잘 보호하십시오.

상태: 테스트넷 프리뷰. 에이전트 등록은 아직 게이트웨이 재시작 후 유지되지 않으므로, API 키처럼 다시 만들 수 있는 것으로 취급하십시오.

이전인증

다음요청 한도

마지막 업데이트 11일 전