Skip to main content
POST
/
link-wallet
cURL
curl -X POST 'https://core-api-server.onrender.com/link-wallet' \
  -H 'Content-Type: application/json' \
  -d '{
    "userID": "user-12345",
    "walletAddress": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM"
  }'
{
  "message": "Success! The wallet address has been linked to the user ID.",
  "details": {
    "userID": "user-12345",
    "walletAddress": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM",
    "status": "submitted",
    "transactionId": "5J7X2vK8mWzNfEtY2jDw5mVpL1WzNfEtYKJH2mNqR3pB",
    "explorerUrl": "https://explorer.solana.com/address/8kQv2gFhgRmHq7ZPBx4N9TqJbSx3jDw5mVpL1WzNfEtY?cluster=devnet"
  }
}
Rate Limit: 100 requests per 15 minutes

​
What This Endpoint Does

1

Parameter Validation

Validates user ID format and wallet address using Solana’s Base58 encoding
2

PDA Generation

Creates a Program Derived Address for the relationship using deterministic seeds
3

Duplicate Check

Ensures the wallet isn’t already linked to prevent conflicts
4

On-Chain Storage

Creates an immutable record on the Solana blockchain
5

Server Sponsorship

Transaction fees are paid by the Trust Engine server (no user cost)

​
Understanding User Key Relations

​
Purpose

User key relations enable the Trust Engine to provide user-friendly experiences by linking human-readable identifiers to blockchain addresses.
Permanent Records: User key relations cannot be modified once created on the blockchain.
This ensures:
  • One relationship per wallet (enforced by PDA uniqueness)
  • Deterministic lookups (same wallet always maps to same PDA)
  • Efficient queries (no need to scan all accounts)

Body

application/json
​
userID
string
required

Unique identifier for the user

Maximum length: 200
Example:

"user-12345"

​
walletAddress
string
required

Valid Solana wallet address in Base58 format

Example:

"9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM"

Response

Wallet successfully linked to user ID

​
message
string
required

Success message confirming the link

​
details
object
required

Link creation details

⌘I