> For the complete documentation index, see [llms.txt](https://docs.nexus.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.nexus.xyz/api-reference/ko/guides/agent-keys.md). # 에이전트 키 세 가지 작업으로 이루어진 에이전트 키 등록 및 관리. **에이전트**는 메인 지갑을 노출하지 않고 사용자를 대신해 거래 요청에 서명할 수 있는 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) 서명이 등록을 승인합니다. **도메인** ```json { "name": "Nexus Exchange", "version": "1", "chainId": "", "salt": "" } ``` **타입** ``` RegisterAgent { address agent uint64 expiresAt uint64 nonce } ``` 중요한 세부 사항: * 서명은 `agent`, `expiresAt`, `nonce`의 **세 개** 필드를 대상으로 합니다. 소유 `wallet`은 타입 데이터에 포함되지 **않습니다**. 지갑 주소는 요청 본문에 함께 보내며, 서버는 복원된 서명자가 이 주소와 일치하는지 확인합니다. * 타입 데이터 필드 이름은 **camelCase**(`expiresAt`)이고, JSON 요청 본문은 **snake\_case**(`expires_at`)를 사용합니다. camelCase 이름으로 서명하고, snake\_case 이름으로 보내십시오. * `expires_at`을 서버 측 기본값에 맡기면 서명할 값이 없습니다. 만료 시각을 직접 계산해 서명하고, 명시적으로 보내십시오. * 계약은 도메인의 `chainId`를 자리표시자 ``로 적을 뿐 값을 고정하지 않습니다. 체인 ID의 기준은 배포 환경입니다. 해당 게이트웨이의 `GET /metadata`에서 읽으십시오([네트워크](/api-reference/ko/guides/networks.md#what-a-network-carries) 참조). 도메인이 일치하지 않으면 설명적인 오류가 아니라 `signer_mismatch`가 발생하므로, 서명하기 전에 대상 게이트웨이가 기대하는 값을 확인하십시오. * 도메인에는 `salt`도 포함됩니다. 값은 `keccak256()`이며, 여기서 ``는 서명 대상 게이트웨이의 소문자 배포 이름(`"mainnet"`, `"testnet"` 또는 `"local"`)입니다. 이 값은 `RegisterAgent` 서명을 하나의 배포 환경으로 한정합니다. `chainId`가 우연히 일치하더라도 같은 서명은 다른 네트워크에서 유효하지 않습니다. 잘못된 `salt`는 다른 신호 없이 `signer_mismatch`만 발생시키므로, 직접 다시 계산하지 말고 대상 배포 환경의 salt 값을 조회하십시오. *** ## `POST /agents/register` 에이전트 키를 등록합니다. 지갑에 새 에이전트 키를 등록합니다. 에이전트는 메인 지갑을 노출하지 않고 사용자를 대신해 거래 요청에 서명할 수 있는 Ethereum 기반 키 쌍입니다. 에이전트를 소유할 지갑의 EIP-712 서명이 등록을 승인합니다. 세션 토큰은 필요하지 않습니다. EIP-712 도메인: `{ name: 'Nexus Exchange', version: '1', chainId: , 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`. 해당 에이전트 주소는 이미 이 지갑에 등록되어 있습니다. ### 예시 ```bash 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..." }' ``` 응답: ```json { "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 인증이 필요합니다. ### 예시 ```bash curl 'https://api.testnet.nexus.xyz/v1/agents' \ -H "X-API-Key: nx_a1b2c3d4e5f67890" \ -H "X-Timestamp: $TIMESTAMP" \ -H "X-Signature: $SIGNATURE" ``` 응답: ```json [ { "address": "0x1234567890AbCdEf1234567890AbCdEf12345678", "expiresAt": 1782000000000, "registeredAt": 1779000000000, "label": "my-bot" } ] ``` `X-Timestamp`와 `X-Signature`를 만드는 방법은 [인증](/api-reference/ko/guides/authentication.md#signing-a-request-with-the-key)을 참조하십시오. *** ## `DELETE /agents/{address}` 에이전트 권한을 해제합니다. 에이전트 키의 권한을 즉시 해제합니다. 이 호출이 반환된 후, 서버는 권한이 해제된 에이전트가 서명한 처리 중인 요청을 모두 거부합니다. **인증:** `hmacAuth`(HMAC API 키). ### 파라미터 | 이름 | 위치 | 타입 | 필수 | 설명 | | --------- | ---- | ------ | -- | ----------------------- | | `address` | path | string | 예 | 권한을 해제할 에이전트 주소(0x 접두사) | ### 응답 #### `200` 에이전트 권한이 해제되었습니다. #### `401` HMAC 인증이 필요합니다. #### `404` 에이전트를 찾을 수 없거나 사용자 소유가 아닙니다. 소유권 확인 실패는 `403`이 아니라 `404`를 반환하므로, 다른 지갑의 에이전트를 탐색할 수 없습니다. ### 예시 ```bash 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 키처럼 다시 만들 수 있는 것으로 취급하십시오. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.nexus.xyz/api-reference/ko/guides/agent-keys.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.