Transfer Codes API

Create, manage, and redeem transfer codes for asset transfers between users.

Create Transfer Code {#create}

Create a new transfer code for an asset you own.

Endpoint

POST /api/v1/transfer-codes

Authentication

Required - Must own the asset

Request Body

{
  "assetId": 12345,
  "expires": "2024-12-31T23:59:59Z"
}

Request Fields

Response

{
  "code": "ABC-DEFG-HIJ",
  "created": 1699999999,
  "modified": 1699999999,
  "assetId": 12345,
  "accId": "user123",
  "state": "ACTIVE",
  "expires": 1704067199,
  "asset": { /* full asset details */ }
}

Notes

• Code format: 12-character alphanumeric (XXX-XXXX-XXX)
• Only one active transfer code per asset
• If no expiration provided, code never expires

List My Transfer Codes {#list}

Get transfer codes created by you.

Endpoint

GET /api/v1/transfer-codes

Authentication

Required

Query Parameters

Response

{
  "transferCodes": [
    {
      "code": "ABC-DEFG-HIJ",
      "created": 1699999999,
      "assetId": 12345,
      "accId": "user123",
      "state": "ACTIVE",
      "asset": {}
    }
  ],
  "total": 10
}

Notes

• Returns only codes you created
• Automatically updates expired codes during retrieval

List Redemptions (Codes You Created) {#list-redemptions}

Get codes you created that were redeemed by others.

Endpoint

GET /api/v1/transfer-codes/redemptions

Authentication

Required

Query Parameters

Response

{
  "redemptions": [
    {
      "code": "ABC-DEFG-HIJ",
      "accId": "claimer123",
      "claimedDate": "2024-11-15 10:30:00",
      "transferCode": {}
    }
  ],
  "total": 5
}

List My Redemptions {#list-my-redemptions}

Get codes you redeemed.

Endpoint

GET /api/v1/transfer-codes/my-redemptions

Authentication

Required

Query Parameters

Response

{
  "redemptions": [
    {
      "code": "ABC-DEFG-HIJ",
      "accId": "user123",
      "claimedDate": "2024-11-15 10:30:00",
      "transferCode": { /* full transfer code details */ }
    }
  ],
  "total": 3
}

Get Transfer Code {#get}

Get transfer code details (owner only).

Endpoint

GET /api/v1/transfer-codes/{code}

Authentication

Required - Must own the code

Path Parameters

Response

{
  "code": "ABC-DEFG-HIJ",
  "created": 1699999999,
  "assetId": 12345,
  "accId": "user123",
  "state": "ACTIVE",
  "expires": 1704067199,
  "asset": {}
}

Notes

• Code automatically marked EXPIRED if past expiration
• Returns 404 if code doesn't exist or not owned by you

Cancel Transfer Code {#cancel}

Cancel an active transfer code.

Endpoint

POST /api/v1/transfer-codes/{code}/cancel

Authentication

Required - Must own the code

Path Parameters

Response

{
  "code": "ABC-DEFG-HIJ",
  "created": 1699999999,
  "assetId": 12345,
  "state": "CANCELED",
  "expires": 1699999999
}

Notes

• Code must be ACTIVE to cancel
• Cannot cancel CLAIMED, EXPIRED, or CANCELED codes
• Sets state to CANCELED and expires to current time

Preview Transfer Code {#preview}

Preview a transfer code (any authenticated user).

Endpoint

GET /api/v1/transfer-codes/{code}/preview

Authentication

Required

Path Parameters

Response

{
  "code": "ABC-DEFG-HIJ",
  "created": 1699999999,
  "assetId": 12345,
  "accId": "user123",
  "state": "ACTIVE",
  "asset": {}
}

Notes

• Any authenticated user can preview
• Returns code state even if not active
• Useful for checking validity before redemption

Redeem Transfer Code {#redeem}

Redeem a transfer code to receive the asset.

Endpoint

POST /api/v1/transfer-codes/{code}/redeem

Authentication

Required - Must NOT be the code owner

Path Parameters

Response

{
  "success": true
}

Error Responses

Redemption Process

1. Validates code is ACTIVE and not expired
2. Verifies you don't own the code
3. Confirms original owner still has asset
4. Uses database transaction for atomicity
5. Records redemption in transfer_codes_claimed
6. Transfers asset ownership to you
7. Posts TRANSFER_CODE_REDEEMED to Dragonchain
8. Marks code as CLAIMED

Notes

• Cannot redeem your own codes
• Asset must still be owned by code creator
• Transaction rolled back on any error