Authentication

Authentication API

POST /oauth/init

Initialize OAuth (Google/Twitter/Telegram).

{
  "provider": "google" | "twitter" | "telegram",
  "redirect_uri": "https://yourapp.example/callback",
  "state": "random-string",
  "code_challenge": "base64url_sha256(code_verifier)"
}

Success

{ "client_id": "string", "url": "string" }

Errors: 400 invalid provider/duplicate state; 500 create failed.

GET /oauth/callback

Handles provider callback; redirects to your redirect_uri with:

?wallet_oauth_provider=...&wallet_oauth_state=...&wallet_oauth_code=...

Errors: 400 invalid state; 500 fetch failed.

POST /send_verification

Send verification code to email or phone. Body: { "email": "string" } or { "phone": "+8612312341234" } Success: "Verification code sent" Errors: 400 invalid/rate limited; 500 send failed.

GET /challenge

Get a challenge message for external-wallet login. Query

  • method: phantom | okx | rabby | metamask | coinbase

  • id: wallet address (Solana for phantom/okx; EVM for others)

Success

{ "challenge": "string", "nonce": "string", "expires_at": 1751246379 }

Errors: 400 invalid params; 500 error.

POST /login

Authenticate via OAuth, OTP, or challenge signature.

Google OAuth

{ "type": "GoogleOAuth", "data": { "state": "string", "code": "string", "code_verifier": "string" } }

Twitter OAuth

{ "type": "TwitterOAuth", "data": { "state": "string", "code": "string", "code_verifier": "string" } }

Apple

{ "type": "Apple", "data": { "id": "string", "identity_token": "string" } }

Email / Phone

{ "type": "Email", "data": { "email": "[email protected]", "code": "123456" } }
{ "type": "Phone", "data": { "phone": "+8612312341234", "code": "123456" } }

Phantom (Solana)

{
  "type": "Phantom",
  "data": { "wallet_address": "string", "challenge": "string", "signature": "string" }
}

Telegram (Direct)

{
  "type": "Telegram",
  "data": {
    "id": 13312222,
    "first_name": "string",
    "last_name": "string",
    "username": "string",
    "photo_url": "string",
    "auth_date": 1341234231,
    "hash": "string"
  }
}

Telegram (OAuth)

{ "type": "TelegramOAuth", "data": { "state": "string", "code": "string" } }

Success

{
  "id": "uuid",
  "wallets": [
    { "id": "string", "address": "string", "network": "Solana", "wallet_type": "Embedded" },
    { "id": "string", "address": "string", "network": "Ethereum", "wallet_type": "Embedded" }
  ],
  "social_links": [ { "Email": "[email protected]" } ]
}

Errors: 400 invalid creds/code; 401 auth failed; 500 server error.

GET /session

Current user session. Success: (see Sessions page for example) Errors: 401 not authenticated.

POST /logout

End session. Success: "Logged out successfully" Errors: 500 destroy failed.

POST /bind

Same payloads as /login, but requires an existing session. Binds another login method.

PreviousAPI Reference DocsNextWallets

Last updated