MIJI DApp Server Docs

Transfer API Guide

모든 Transfer API는 x-api-key + X-CORPORATE-ID 헤더를 동시에 요구합니다. X-CORPORATE-ID는 corporateAccounts 컬렉션에 등록된 기업 식별자이며, Transfer 주문/조회는 해당 기업 범위로만 스코프됩니다.

공통 헤더

Name Required Value
x-api-key ✅ 서버에 등록된 글로벌 API 키
X-CORPORATE-ID ✅ corporateAccounts._id 또는 corporateId
Content-Type ⚠️ JSON Body가 있는 요청에서 application/json

POST /transfer/signature 역시 동일한 헤더를 요구하지만, TRANSFER_TEST_SIGNATURE=true인 개발 환경에서만 접근 가능합니다.

POST /transfer/signature (Dev Only)

테스트 환경에서 MinimalForwarder용 EIP-712 payload/서명을 생성합니다.
privateKey를 제공하면 해당 키로 서명하고, 제공하지 않으면 서버의 LOCAL_DEV_PRIVATE_KEY로 서명합니다.
운영 환경에서는 프런트엔드/지갑이 같은 규격으로 직접 서명을 생성해야 합니다.

Request Body

필드 타입 필수 설명
chainId string ✅ 예: 43113
contractAddress string ✅ 배포된 ERC-721/1155 주소
ercStandard 721 \| 1155 ❌ 미입력 시 DB 기준으로 자동 결정
tokenId string ✅ 전송할 토큰 ID
amount number ❌ ERC-1155 only (default 1)
from address ✅ 토큰 보유자
to address ✅ 수신자
gasLimit number ❌ Forwarder request gas (기본 500,000)
forwarderAddress address ❌ 특정 Forwarder 지정 필요 시
privateKey string ❌ 테스트용 서명 개인키 (제공 시 해당 키로 서명)
note string ❌ 메모

Response

{
  "domain": {
    "name": "MinimalForwarder",
    "version": "1.0",
    "chainId": 43113,
    "verifyingContract": "0xForwarder..."
  },
  "types": {
    "ForwardRequest": [
      { "name": "from", "type": "address" },
      { "name": "to", "type": "address" },
      { "name": "value", "type": "uint256" },
      { "name": "gas", "type": "uint256" },
      { "name": "nonce", "type": "uint256" },
      { "name": "data", "type": "bytes" }
    ]
  },
  "request": {
    "from": "0x...",
    "to": "0xContract...",
    "value": "0",
    "gas": "500000",
    "nonce": "3",
    "data": "0x..."
  },
  "signature": "0x..."
}

POST /transfer/execute

외부 지갑에서 생성한 EIP-712 서명을 전달하면, 서버가 Bull 큐를 통해 MinimalForwarder.execute를 호출하여 safeTransferFrom을 대납합니다.

Request Body

필드 타입 필수 설명
chainId string ✅  
contractAddress string ✅  
ercStandard 721 \| 1155 ❌ DB 미존재 시 필수
tokenId string ✅  
amount number ❌ ERC-1155 only
from address ✅ 실제 토큰 보유자 (서명자)
to address ✅ 수신자
signature string ✅ eth_signTypedData_v4 결과
gasLimit number ❌ Forwarder request gas
forwarderNonce string ❌ 지정하지 않으면 서버가 getNonce(from) 호출
forwarderAddress address ❌ 특정 Forwarder 지정 필요 시

Response (201) / GET Response

TransferOrderResponseDto

{
  "id": "692e84f3d3e3deac5d7f7ba6",
  "chainId": "43113",
  "contractAddress": "0x9e9b178cf24bd802dfbdd97435c94e9289f9a91e",
  "from": "0x08a02c036fadcaf5c47a6b1a4a26a19bf71c18e7",
  "to": "0x5a6be23be47d5dd4e1d3324a6b8c2975c910165f",
  "tokenId": "111",
  "amount": 1,
  "ercStandard": "721",
  "status": "CONFIRMED",
  "txHash": "0x092d18e28cef3cb7a90fe2ae44164f6f2a2f8631639c6f3f37e1a9f72d31d7c1",
  "transferGasUsed": "25136",
  "totalFeeAvax": "0.000000000000050272",
  "avaxPriceUsd": 12.93,
  "totalFeeUsd": 6.5001696e-13,
  "avaxPriceKrw": 18993.95,
  "totalFeeKrw": 9.548638544e-10,
  "createdAt": "2025-12-02T06:19:31.375Z",
  "updatedAt": "2025-12-02T06:19:36.099Z",
  "completedAt": "2025-12-02T06:19:36.098Z"
}

GET /transfer/:id

Transfer 주문 상태를 조회합니다. 응답 구조는 위 TransferOrderResponseDto와 동일합니다.

GET /transfer/by-tx/:txHash

Tx Hash로 Transfer 주문을 조회합니다.
txHash는 소문자로 저장되므로, 대소문자 구분 없이 요청 가능합니다.

운영 시 주의 사항

  1. TRUSTED_FORWARDER에 MinimalForwarder 주소를 설정해야 하며, NFTs는 해당 forwarder를 신뢰하도록 배포/업데이트되어야 합니다.
  2. TRANSFER_TEST_SIGNATURE=true는 개발 전용입니다. 운영 환경에서는 반드시 false로 유지하고, 클라이언트가 직접 Metamask 등으로 서명하게 하세요.
  3. Forwarder nonce는 forwarder.getNonce(from)을 사용해 동기화해야 하며, 서버가 자동으로 검증합니다.
  4. Transfer 실패 시(서명 위조, 토큰 소유 불일치 등)는 status=FAILED, errorMessage를 확인하고 재시도하면 됩니다.