Register Wallet - Turtle Docs

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

Check Membership Status

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

Request Signature Agreement

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

Create Membership

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

Endpoints

Check Membership Status

GET /v2/membership/

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 -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 -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 RequestResponse:

{
  "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 RequestResponse:

{
  "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 ConflictResponse:

{
  "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 RequestResponse:

{
  "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

​Overview

​Authentication Flow

​Endpoints

​Check Membership Status

​Response Example

​Response Fields

​Request Signature Agreement

​Response Example

​Response Fields

​Create Membership

​Response Example

​Response Fields

​Complete Flow Example

​Error Handling

​Common Errors

​Security Considerations

Overview

Authentication Flow

Endpoints

Check Membership Status

Response Example

Response Fields

Request Signature Agreement

Response Example

Response Fields

Create Membership

Response Example

Response Fields

Complete Flow Example

Error Handling

Common Errors

Security Considerations