HingeSDK

Unofficial Python SDK for the Hinge API. Programmatically interact with Hinge to fetch recommendations, send messages, download media, and automate interactions.

Authentication & Environment Setup

To use this SDK, you need valid authentication credentials. You can store these in a .env file or pass them directly to the client.

Required Variables

• BEARER_TOKEN: Your JWT authentication token (e.g., L2euNWN...).
• SESSION_ID: The current session UUID.
• USER_ID: Your unique user/player ID.

How to Get Credentials

Method 1: Rooted Phone / Proxy (Recommended for Existing Accounts)

If you want to use your existing Hinge account without risking flags from new device logins, you must extract these values from the app's network traffic.

Note: You only need to do this once to obtain the correct variables. After capturing them, you can use the SMS Login method for future sessions.

1. Use a rooted Android device or a standard proxy setup (e.g., with HTTP Toolkit or Charles Proxy) since Hinge does not use certificate pinning.
2. Inspect HTTPS requests to prod-api.hingeaws.net or similar Hinge endpoints.
3. Extract the following headers/values from the request or response bodies of profile endpoints:
   • authorization (Bearer token)
   • x-session-id
   • x-device-id
   • x-install-id
   • User ID (often in the response body as subjectId or similar)

Method 2: SMS Login (Experimental)

You can generate new credentials by logging in via SMS through the SDK. This performs a fresh login flow.

from hingesdk.client import HingeClient

# These IDs must match the actual values associated with your account.
# You cannot use random UUIDs; they must align with the account's registered device.
client = HingeClient.login_with_sms(
    phone_number="+15551234567", 
    device_id="your_device_id_uuid", 
    install_id="your_install_id_uuid" 
)

print(f"BEARER_TOKEN={client.auth_token}")
print(f"SESSION_ID={client.session_id}")
print(f"USER_ID={client.user_id}")

Installation

Clone the repository and install the package:

git clone https://github.com/reedgraff/hingesdk
cd hingesdk
pip install .

Quick Start

Here is a minimal example to authenticate and fetch user recommendations.

import os
from hingesdk.api import HingeAPIClient

# Initialize with credentials
client = HingeAPIClient(
    auth_token=os.getenv("BEARER_TOKEN"),
    session_id=os.getenv("SESSION_ID"),
    user_id=os.getenv("USER_ID")
)

# Fetch recommendations
recs = client.get_recommendations()
print(f"Successfully fetched recommendations request.")

Usage & Examples

from hingesdk.client import HingeAPIClient

auth_token = 'your_auth_token'
user_id = 'your_user_id'

client = HingeAPIClient(auth_token=auth_token, user_id=user_id)
response = client.send_message(
    subject_id='receiver_id',
    message='Hello, this is a test message!'
)
print(response)

from hingesdk.api import HingeAPIClient

client = HingeAPIClient(auth_token=auth_token, user_id=user_id)
recommendations = client.get_recommendations()
print(recommendations)

from hingesdk.tools import HingeTools
from hingesdk.api import HingeAPIClient
from hingesdk.media import HingeMediaClient

api_client = HingeAPIClient(auth_token=auth_token, user_id=user_id)
media_client = HingeMediaClient(auth_token=auth_token)

tools = HingeTools(api_client, media_client)
tools.download_recommendation_content(output_path='path_to_save_images')

import os
import json
from hingesdk.tools import HingeTools
from hingesdk.api import HingeAPIClient
from hingesdk.media import HingeMediaClient

auth_token = os.getenv("BEARER_TOKEN")
session_id = os.getenv("SESSION_ID")
user_id = os.getenv("USER_ID")

api_client = HingeAPIClient(
    auth_token=auth_token,
    session_id=session_id,
    user_id=user_id
)
media_client = HingeMediaClient(auth_token=auth_token)
tools = HingeTools(api_client, media_client)

# Example: Get user info
tools.create_profile_json(
    source=ProfileSource.STANDOUTS,
    output_file="standouts.json"
)

# Example: Like a user 
with open("standouts.json", "r") as f:
    profiles = json.load(f)

personData = profiles["35582109789..."]

# Like a user's question
questionIDToLike = "5c4a346828fd883a24..."
response = api_client.like_profile(
    subject_id=personData["interaction_data"]["subject_id"],
    rating_token=personData["interaction_data"]["rating_token"],
    prompt={
        "questionId": questionIDToLike,
        "response": "I've been in Miami for a year and still haven't gone (╥﹏╥)"
    }
)
print(response)

# Like a user's photo
# photoIDToLike = "2c6411ac-66e4-4194-..."
# response = api_client.like_profile(
#     subject_id=personData["interaction_data"]["subject_id"],
#     rating_token=personData["interaction_data"]["rating_token"],
#     photo={
#         "contentId": photoIDToLike,
#         "comment": "So how many people have commented saying they've been here before?"
#     }
# )
# print(response)