Get Or Create Holder

Endpoint: PUT /holder/:userId | Auth: πŸ”’ Secret Key | Purpose: Create or retrieve holder wallet

πŸ€– AI Implementation Summary:

  • Usage: Call during user signup to create wallet for token operations
  • Parameters: userId - Your internal user identifier (email, UUID, etc.)
  • Returns: Wallet address for future token operations
  • Workflow: User signup β†’ Call this endpoint β†’ Store returned address

Get Or Create a Holder for your organization. Holder wallets can be created for your customers with an custom user id of your choice.


PUTapi.metal.build/holder/:userId

Get Or Create a Holder

This endpoint returns a user's holder address if the user exists. If the user does not exist, a wallet will be created for them using a custom external id of your choice.

⚑

AI Implementation Tip

This is typically called during user signup. The userId should be your internal user identifier (email, UUID, etc.). Store the returned wallet address for future token operations.


Required attributes

  • Name
    userId
    Type
    string
    Description

    The external id for your holder (e.g., "1234567890"). Must be a stable string.

Response attributes

  • Name
    id
    Type
    string
    Description

    The id of the holder. This is the same as userId which you made the request with.

  • Name
    address
    Type
    string
    Description

    The address of the holder.

  • Name
    totalValue
    Type
    number
    Description

    Total value of all token holdings in USD (including active tokens, locked tokens, and presales).

  • Name
    tokens
    Type
    array
    Description

    Array of active (unlocked) token objects, each containing. See example below.

  • [
      {
        "id": "string",
        "address": "string",
        "name": "string",
        "symbol": "string",
        "balance": "number",
        "value": "number",
        "status": "active",
        "type": "token"
      }
    ]
    
  • Name
    presales
    Type
    array
    Description

    Array of presale participation objects, each containing. See example below.

  • [
      {
        "id": "string",
        "address": "string",
        "name": "string",
        "symbol": "string",
        "balance": "number", // Expected tokens to receive
        "value": "number", // USDC invested
        "status": "pending",
        "type": "presale",
        "metadata": {
          "presaleId": "string",
          "progress": "number", // Percentage complete
          "endDate": "string" // ISO date
        }
      }
    ]
    
  • Name
    locks
    Type
    array
    Description

    Array of locked token objects, each containing. See example below.

  • [
      {
        "id": "string",
        "address": "string",
        "name": "string",
        "symbol": "string",
        "balance": "number", // Locked amount
        "value": "number",
        "status": "locked",
        "type": "lock",
        "unlockDate": "string" // ISO date when tokens unlock
      }
    ]
    

Request

PUT
api.metal.build/holder/:userId
const response = await fetch(`https://api.metal.build/holder/1234567890`, {
method: 'PUT',
headers: {
  'Content-Type': 'application/json',
  'x-api-key': 'YOUR_SECRET_API_KEY',
  },
})

const holder = await response.json()

Response

{
  "success": true,
  "id": "1234567890",
  "address": "0x38A7ff01f9A2318feA8AafBa379a6c2c18b5d1dc",
  "totalValue": 0,
  "tokens": [],
  "presales": [],
  "locks": []
}

Was this page helpful?