Wallet Linking

Why link a wallet

Wallet linking may be used to connect supported wallet based account features where available. Current billing rules, credits, and account benefits are shown on the live pricing page.

Linking a wallet associates a wallet address with the authenticated account or agent path after ownership has been proven by signature.

Endpoint

POST /v1/agents/link-wallet

Requires authentication via X-API-Key header.

Request

curl -X POST https://agents.systemr.ai/v1/agents/link-wallet \
  -H "X-API-Key: sr_agent_..." \
  -H "Content-Type: application/json" \
  -d '{
    "solana_wallet_address": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
    "signature": "BASE58_ENCODED_SIGNATURE",
    "message": "Link wallet to agent agt_a1b2c3d4"
  }'

Parameters

How signature verification works

1. You create a message string that includes your agent_id (e.g., "Link wallet to agent agt_a1b2c3d4").
2. You sign the message using your Solana wallet's private key (Ed25519).
3. You send the wallet address, signature, and message to the endpoint.
4. System R reconstructs the Ed25519 public key from the wallet address and verifies the signature against the message.

This proves you own the wallet without revealing the private key.

Signing the message

Using Phantom wallet (browser)

const message = `Link wallet to agent ${agentId}`;
const encodedMessage = new TextEncoder().encode(message);
const signedMessage = await window.solana.signMessage(encodedMessage, "utf8");
const signature = bs58.encode(signedMessage.signature);

Using Python (solders)

from solders.keypair import Keypair
import base58
 
keypair = Keypair.from_bytes(your_private_key_bytes)
message = f"Link wallet to agent {agent_id}"
message_bytes = message.encode("utf-8")
signature = keypair.sign_message(message_bytes)
signature_b58 = base58.b58encode(bytes(signature)).decode("utf-8")

Response

{
  "agent_id": "agt_a1b2c3d4",
  "solana_wallet_address": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
  "message": "Wallet linked successfully"
}

The exact response fields can depend on the currently enabled account features and API version.

Account features

Wallet based account features are availability dependent. Use the live pricing page and current billing endpoints as the source of truth for account rules, credits, and payment behavior.

Security

The wallet address is stored as sensitive account data and should be handled as part of the same security model used for account credentials and agent access.