친구에게 20 USDC를 보내기 위해 채팅 앱에서 16진수 문자열(hex string)을 복사하고, 체인을 확인하며, 네트워크가 일치하기를 기도해야 해서는 안 됩니다. @cai.com 디렉토리는 지갑 주소를 핸들(handle)로 대체합니다. 이름을 입력하고, 핸들을 선택하면 돈이 이동합니다.

이 포스트에서는 @cai.com 주소 디렉토리, 핸들을 지갑으로 확인(resolve)하는 방법, 그리고 사용자가 16진수 문자열을 전혀 보지 않고 개인 간 결제(person-to-person payments)가 이루어지는 방식에 대해 다룹니다.

디렉토리

@cai.com 디렉토리는 등록된 모든 사용자를 6개의 체인에 걸친 수탁 지갑 주소(custodial wallet addresses)에 매핑합니다. cai.com/app에서 가입하면 alice@cai.com과 같은 핸들과 지원되는 각 체인의 지갑 주소를 받게 됩니다. 디렉토리는 이 매핑 정보를 저장합니다.

이 디렉토리는 블록체인 자체가 아닙니다. 이는 CAI가 유지 관리하는 조회 테이블(lookup table)입니다. 누군가에게 결제해야 하는 에이전트(agent)는 수신자의 이메일 또는 핸들을 사용하여 resolve-transfer-recipient를 호출하고, 요청된 체인에서의 정식 주소(canonical address)를 반환받습니다.

API 호출은 간단합니다:

curl -sS https://api.cai.com/functions/v1/resolve-transfer-recipient \
  -H "Authorization: Bearer ***" \
  -H "Content-Type: application/json" \
...

응답:

{
  "canonical_email": "friend@cai.com",
  "to_address": "0x..."
...

디렉토리를 통한 결제 방식

주소가 확인되면 에이전트가 전송을 시작합니다. 사용자는 호스팅된 액션(hosted-action) 페이지에서 이를 확인하며, CAI는 요청된 체인에서 수탁 전송(custodial transfer)을 실행합니다.

curl -sS https://api.cai.com/functions/v1/wallet-custodial-transfer \
  -H "Authorization: Bearer ***" \
  -H "Content-Type: application/json" \
...

to_email 필드에 주목하세요. 에이전트는 지갑 주소를 전혀 다루지 않습니다. 핸들을 확인(resolve)한 다음, 그 핸들을 다시 전송 엔드포인트(transfer endpoint)로 전달합니다. CAI는 두 번째 호출 시 내부적으로 주소 확인(address resolution)을 처리합니다.

공개 인터페이스 (The public surface)

이 디렉토리는 공개적인 측면(public facing side)도 가지고 있습니다. cai.com/.well-known/agent.json 파일은 다른 에이전트(agent)들이 CAI와 상호작용하는 방법을 발견할 수 있게 해주는 A2A 에이전트 카드(Agent Card)입니다. cai.com/capabilities.html 페이지는 어떤 기능이 라이브(live) 상태인지, 어떤 기능이 베타(beta) 단계인지, 그리고 어떤 기능이 Gap ID를 포함하고 있는지를 나열합니다.

특히 @cai.com 주소 디렉토리에 대해서는 다음과 같습니다:

• 라이브 (Live) (capabilities.html 기준): 디렉토리가 운영 중입니다. 모든 등록된 사용자는 그들의 @cai.com 핸들(handle)을 통해 검색 가능합니다.
• 체인 지원 (Chain support): ETH, BASE, POLYGON, SOLANA, ARBITRUM, OPTIMISM.
• Gap ID: GAP_RESOLVE_V1 — 해결(resolution) 기능이 라이브 상태이지만 모든 예외 케이스(edge case)를 다루지 않을 수 있음을 나타냅니다 (예: 등록되지 않은 핸들은 조용히 실패하는 대신 명확한 에러를 반환함).

에이전트에게 이것이 의미하는 바

누군가에게 결제해야 하는 에이전트는 지갑 주소(wallet address)를 물어볼 필요가 없습니다. 대신 그 사람의 @cai.com 핸들을 요청합니다. 에이전트는 이를 해결(resolve)하고, 잔액을 확인한 뒤, 송금을 시작합니다. 사용자는 한 번의 탭으로 이를 승인합니다.

에이전트가 프리랜서에게 비용을 지불하든, 나누어 내야 할 계산서를 정산하든, 혹은 집주인에게 정기 결제를 보내든 이 흐름은 동일합니다. 디렉토리는 체인의 복잡성을 추상화(abstract)합니다. 에이전트는 주소가 아닌 이름으로 작동합니다.

엔드 투 엔드 (The end-to-end)

디렉토리를 통한 완전한 결제 흐름은 다음과 같습니다:

1. 에이전트가 get-identity를 호출하여 사용자가 CAI 계정을 보유하고 있는지 확인합니다.
2. 에이전트가 사용자에게 수취인의 @cai.com 핸들을 묻습니다.
3. 에이전트가 핸들과 선호하는 체인을 사용하여 resolve-transfer-recipient를 호출합니다.
4. 에이전트가 get-wallet-balances를 호출하여 충분한 자금이 있는지 확인합니다.
5. 에이전트가 수취인의 핸들을 사용하여 wallet-custodial-transfer를 호출합니다.
6. 사용자가 호스팅된 액션(hosted-action) 페이지에서 승인합니다.
7. 에이전트가 wallet-activity-list를 통해 결제가 완료되었음을 확인합니다.

모든 단계는 핸들을 기반으로 작동합니다. 에이전트는 개인 키(private key)를 절대 보지 않으며, 16진수 주소(hex address)를 복사하지도 않고, 수취인이 어떤 네트워크에 있는지 묻지도 않습니다.

문서: cai.com/skill.md · cai.com/developers.html · 가입하려면 cai.com/app을 방문하세요.

만약 이 흐름을 시도하다가 버그(bug)를 발견했다면, 실행한 명령(command), 예상했던 결과, 그리고 실제 발생한 결과를 아래에 댓글로 남겨주세요. 버그 보고(Bug reports)에는 24시간 이내에 답변을 드립니다.