Register Wallet

Connect wallets and create memberships in Turtle

All requests require an API key via the X-API-Key header. See Authentication for details.

Overview

Before a wallet can interact with any action endpoint, it must be registered as a Turtle member. Membership links a wallet address to a Turtle user, which is what enables deposit attribution and revenue tracking. Supported ecosystems are EVM (Ethereum, Arbitrum, Base, and every supported EVM chain), Solana, and TON.

The Membership API follows a three-step flow that proves wallet ownership: check membership, request a sign-in message, then submit the signed message.

Action endpoints reject an unregistered wallet.

Authentication Flow

1. Check Membership Status

   Verify if a wallet address is already associated with a Turtle account

2. Request Signature Agreement

   Generate a message that must be signed by the wallet to prove ownership

3. Create Membership

   Submit the signed message to create a new user account and associate the wallet

Endpoints

Check Membership Status

GET /v2/membership/

curl

curl -X GET "https://earn.turtle.xyz/v2/membership/?address=0xaD595ba34B6BEdCdFDecCe0C0cDe6A2Dc7Ad658D&walletEcosystem=evm" \
  -H "X-API-Key: pk_live_xxxxx"

const response = await fetch(
  'https://earn.turtle.xyz/v2/membership/?address=0xaD595ba34B6BEdCdFDecCe0C0cDe6A2Dc7Ad658D&walletEcosystem=evm',
  { headers: { 'X-API-Key': 'pk_live_xxxxx' } }
);
const data: { isMember: boolean } = await response.json();

Query Parameters

address · string · required

The wallet address to check

walletEcosystem · string · default: "evm"

The blockchain ecosystem. Supported values: evm, solana, ton

Response Example

{
  "isMember": false
}

Response Fields

isMember · boolean

Whether the wallet address is already associated with a Turtle account.

Request Signature Agreement

POST /v2/membership/agreement

curl

curl -X POST https://earn.turtle.xyz/v2/membership/agreement \
  -H "X-API-Key: pk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "address": "0xaD595ba34B6BEdCdFDecCe0C0cDe6A2Dc7Ad658D",
    "walletEcosystem": "evm",
    "url": "https://turtle.xyz",
    "chainId": "1"
  }'

const response = await fetch('https://earn.turtle.xyz/v2/membership/agreement', {
  method: 'POST',
  headers: { 'X-API-Key': 'pk_live_xxxxx', 'Content-Type': 'application/json' },
  body: JSON.stringify({
    address: '0xaD595ba34B6BEdCdFDecCe0C0cDe6A2Dc7Ad658D',
    walletEcosystem: 'evm',
    url: 'https://turtle.xyz',
    chainId: '1',
  }),
});
const data: { nonce: string; message: string } = await response.json();

Request Body

address · string · required

The wallet address requesting membership

walletEcosystem · string · required

The blockchain ecosystem. Supported values: evm, solana, ton

url · string · required

The URL of the application (used in the signature message)

chainId · string · default: "1"

The chain ID for EVM wallets. Not required for Solana or TON

Response Example

{
  "nonce": "550e8400-e29b-41d4-a716-446655440000",
  "message": "turtle.xyz wants you to sign in with your Ethereum account:\n0xaD595ba34B6BEdCdFDecCe0C0cDe6A2Dc7Ad658D\n\nSign Up to Turtle\n\nURI: https://turtle.xyz\nVersion: 1\nChain ID: 1\nNonce: 550e8400-e29b-41d4-a716-446655440000\nIssued At: 2024-01-15T10:00:00Z"
}

Response Fields

nonce · string

A single-use nonce that must be included when submitting the signed message.

message · string

The EIP-4361 sign-in message the wallet must sign to prove ownership.

Create Membership

POST /v2/membership/

curl

curl -X POST https://earn.turtle.xyz/v2/membership/ \
  -H "X-API-Key: pk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "address": "0xaD595ba34B6BEdCdFDecCe0C0cDe6A2Dc7Ad658D",
    "walletEcosystem": "evm",
    "signature": "0x1234567890abcdef...",
    "nonce": "550e8400-e29b-41d4-a716-446655440000",
    "distributorId": "your-distributor-id"
  }'

const response = await fetch('https://earn.turtle.xyz/v2/membership/', {
  method: 'POST',
  headers: { 'X-API-Key': 'pk_live_xxxxx', 'Content-Type': 'application/json' },
  body: JSON.stringify({
    address: '0xaD595ba34B6BEdCdFDecCe0C0cDe6A2Dc7Ad658D',
    walletEcosystem: 'evm',
    signature: '0x1234567890abcdef...',
    nonce: '550e8400-e29b-41d4-a716-446655440000',
    distributorId: 'your-distributor-id', // optional
  }),
});
const data: { isMember: boolean; error: string } = await response.json();

Request Body

address · string · required

The wallet address creating the membership

walletEcosystem · string · required

The blockchain ecosystem. Supported values: evm, solana, ton

signature · string · required

The signature of the message returned by the agreement endpoint

nonce · string · required

The nonce returned by the agreement endpoint

distributorId · string

The distributor ID to associate the membership with. When provided, the user will be tracked as having signed up through the distributor’s integration.

Response Example

{
  "isMember": true,
  "error": ""
}

Response Fields

isMember · boolean

Whether the wallet is now a registered Turtle member.

error · string

An error message when the request fails, or an empty string on success.

Complete Flow Example

Here’s a complete example of the membership creation flow:

curl

# Step 1: Check if wallet is already a member
curl -X GET "https://earn.turtle.xyz/v2/membership/?address=0xaD595ba34B6BEdCdFDecCe0C0cDe6A2Dc7Ad658D&walletEcosystem=evm" \
  -H "X-API-Key: pk_live_xxxxx"
# Response: {"isMember": false}

# Step 2: Request signature agreement
curl -X POST https://earn.turtle.xyz/v2/membership/agreement \
  -H "X-API-Key: pk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "address": "0xaD595ba34B6BEdCdFDecCe0C0cDe6A2Dc7Ad658D",
    "walletEcosystem": "evm",
    "url": "https://turtle.xyz",
    "chainId": "1"
  }'
# Response: {"nonce": "550e8400...", "message": "turtle.xyz wants you to sign..."}

# Step 3: Sign the message with your wallet (using web3 library or wallet app)
# This step happens client-side

# Step 4: Submit the signature to create membership
curl -X POST https://earn.turtle.xyz/v2/membership/ \
  -H "X-API-Key: pk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "address": "0xaD595ba34B6BEdCdFDecCe0C0cDe6A2Dc7Ad658D",
    "walletEcosystem": "evm",
    "signature": "0x1234567890abcdef...",
    "nonce": "550e8400-e29b-41d4-a716-446655440000"
  }'
# Response: {"isMember": true, "error": ""}

# Step 5: Verify membership was created
curl -X GET "https://earn.turtle.xyz/v2/membership/?address=0xaD595ba34B6BEdCdFDecCe0C0cDe6A2Dc7Ad658D&walletEcosystem=evm" \
  -H "X-API-Key: pk_live_xxxxx"
# Response: {"isMember": true}

Error Handling

Common Errors

Invalid Wallet Ecosystem

Status Code: 400 Bad Request

Response:

{
  "error": {
    "status": "INVALID_ARGUMENT",
    "error": "invalid wallet ecosystem"
  }
}

Solution: Use one of the supported ecosystems: evm, solana, or ton

Invalid Wallet Address

Status Code: 400 Bad Request

Response:

{
  "error": {
    "status": "INVALID_ARGUMENT",
    "error": "invalid wallet address"
  }
}

Solution: Ensure the wallet address is valid for the specified ecosystem

Wallet Already Exists

Status Code: 409 Conflict

Response:

{
  "error": {
    "status": "ALREADY_EXISTS",
    "error": "wallet already exists"
  }
}

Solution: This wallet is already associated with an account. You do not need to create a new membership.

Invalid or Expired Nonce

Status Code: 400 Bad Request

Response:

{
  "error": {
    "status": "INVALID_ARGUMENT",
    "error": "invalid nonce or expired"
  }
}

Solution: Request a new agreement and sign it promptly. Nonces expire after a short period

Security Considerations

Never share your private keys or seed phrases. The API only requires signatures, not private keys.

• Nonces are single-use and expire after a short period
• Messages follow the EIP-4361 standard for EVM wallets
• All signatures are verified server-side before creating accounts