# SurferCID API Client
A Python client for interacting with the SurferCID API. This client provides easy access to SurferCID's services including purchasing accounts, creating and refreshing LTokens, checking orders, and managing balance.
## Project Structure
```
surfercid_client/
├── models.py # Data models and response types
├── surfercid_client.py # Main API client implementation
└── requirements.txt # Project dependencies
```
## Installation
1. Install via pip:
```bash
pip install surfercid-client
```
## Usage
```python
from surfercid import SurferCIDClient
from surfercid.models import LTokenAccount, Status
# Initialize the client
client = SurferCIDClient(api_key="your_api_key_here")
# Get stock information for a product
stock_info = client.get_stock("Ltoken_create")
print("Stock Info: ", stock_info)
# Check account balance
balance = client.get_balance()
print("Balance: ", balance)
# Create new LTokens
creation_order = client.create_token(quantity=1)
print(f"Order ID: {creation_order.order_id}")
# Wait for token creation to complete
order = client.get_task_status(creation_order.order_id, wait=True)
if order.status == Status.SUCCESS:
for account in order.accounts:
if isinstance(account, LTokenAccount):
print(f"Token created: {account.to_format()}")
# Outputs: mac:XX:XX:XX:XX:XX:XX|wk:NONE0|platform:1|rid:XXX|name:XXX|cbits:1536|playerAge:25|token:XXX|vid:XXX
# Example of refreshing tokens
if isinstance(account, LTokenAccount):
refreshed = client.refresh_token(account)
print(f"Refreshed token: {refreshed.to_format()}")
```
## Available Methods
### Token Creation and Management
- `create_token(quantity: int = 1) -> OrderResponse`: Create new LTokens
- `get_task_status(order_id: int, wait: bool = False) -> OrderResponse`: Check token creation status
- `refresh_token(token_data: Union[str, LTokenAccount]) -> LTokenAccount`: Refresh an LToken
### Account Management
- `get_stock(product_name: str) -> Dict[str, Any]`: Get stock information for a specific product
- `get_balance() -> float`: Get current account balance
- `purchase(product_name: str, quantity: int) -> OrderResponse`: Purchase products
- `get_order(order_id: int) -> OrderResponse`: Get details of a specific order
- `get_orders(limit: Optional[int] = None) -> List[OrderResponse]`: Get list of orders
## Data Models
### LTokenAccount
```python
@dataclass
class LTokenAccount(Account):
created_at: str
mac: str
name: str
platform: str
rid: str
token: str
wk: str = "NONE0"
cbits: int = 1536
player_age: int = 25
vid: str = ""
def to_format(self) -> str:
"""Convert to the new token format"""
return f"mac:{self.mac}|wk:{self.wk}|platform:{self.platform}|rid:{self.rid}|name:{self.name}|cbits:{self.cbits}|playerAge:{self.player_age}|token:{self.token}|vid:{self.vid}"
```
### OrderResponse
```python
@dataclass
class OrderResponse:
accounts: List[Account]
message: str
success: bool
cost: float
order_id: int
order_date: datetime
processing: bool = False
quantity: int = 0
refund_amount: float = 0
status: Status = Status.FAILED
```
### Status Enum
```python
class Status(Enum):
SUCCESS = "success"
FAILED = "failed"
PROCESSING = "processing"
```
## Error Handling
The client includes comprehensive error handling for various scenarios:
```python
from requests.exceptions import RequestException
try:
# Create a new token
order = client.create_token(quantity=1)
status = client.get_task_status(order.order_id, wait=True)
if status.status == Status.SUCCESS:
print("Token created successfully!")
elif status.status == Status.FAILED:
print(f"Creation failed: {status.message}")
except RequestException as e:
print(f"API request failed: {e}")
except ValueError as e:
print(f"Invalid input or response: {e}")
```
## Token Format
The new token format includes additional fields for enhanced functionality:
```
mac:XX:XX:XX:XX:XX:XX|wk:NONE0|platform:1|rid:XXX|name:XXX|cbits:1536|playerAge:25|token:XXX|vid:XXX
```
Where:
- `mac`: MAC address
- `wk`: World key (default: NONE0)
- `platform`: Platform identifier
- `rid`: Resource identifier
- `name`: Account name
- `cbits`: Client bits (default: 1536)
- `playerAge`: Player age (default: 25)
- `token`: Authentication token
- `vid`: Version identifier
## Token Refresh Examples
### Single Token Refresh
```python
from surfercid import SurferCIDClient
from surfercid.models import LTokenAccount
# Initialize client
client = SurferCIDClient(api_key="your_api_key")
# Create token account from formatted string
token_str = "mac:XX:XX:XX:XX:XX:XX|wk:NONE0|platform:1|rid:XXX|name:XXX|token:XXX"
token = LTokenAccount.from_format(token_str)
# Refresh token
refreshed = client.refresh_token(token)
print(f"New token: {refreshed.to_format()}")
```
### Multiple Tokens Refresh
```python
from surfercid import SurferCIDClient
from surfercid.models import LTokenAccount
def refresh_tokens(api_key: str, tokens_str: str) -> None:
client = SurferCIDClient(api_key=api_key)
# Parse and refresh each token
for line in tokens_str.strip().split('\n'):
if not line.strip():
continue
try:
token = LTokenAccount.from_format(line)
refreshed = client.refresh_token(token)
print(f"✓ Refreshed {token.name}: {refreshed.to_format()}")
except Exception as e:
print(f"✗ Failed to refresh: {e}")
# Example usage
tokens = """
mac:XX:XX:XX:XX:XX:XX|wk:NONE0|platform:1|rid:XXX|name:Token1|token:XXX
mac:YY:YY:YY:YY:YY:YY|wk:NONE0|platform:1|rid:YYY|name:Token2|token:YYY
"""
refresh_tokens("your_api_key", tokens)
```
The examples above demonstrate:
1. Refreshing a single token using a formatted string
2. Batch refreshing multiple tokens from a multi-line string
3. Error handling for failed refreshes
4. Using the key:value format for token strings
Raw data
{
"_id": null,
"home_page": "https://documenter.getpostman.com/view/15842770/2s9YJW55kQt",
"name": "surfercid-client",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "surfercid, api, client, token",
"author": "SurferCID",
"author_email": "HeySurfers@protonmail.com",
"download_url": "https://files.pythonhosted.org/packages/4c/84/78d964191244041bea3b7cf714eaffa1db7474327e65ab402a1050de6433/surfercid_client-0.1.49.tar.gz",
"platform": null,
"description": "# SurferCID API Client\r\n\r\nA Python client for interacting with the SurferCID API. This client provides easy access to SurferCID's services including purchasing accounts, creating and refreshing LTokens, checking orders, and managing balance.\r\n\r\n## Project Structure\r\n\r\n```\r\nsurfercid_client/\r\n\u251c\u2500\u2500 models.py # Data models and response types\r\n\u251c\u2500\u2500 surfercid_client.py # Main API client implementation\r\n\u2514\u2500\u2500 requirements.txt # Project dependencies\r\n```\r\n\r\n## Installation\r\n\r\n1. Install via pip:\r\n```bash\r\npip install surfercid-client\r\n```\r\n\r\n## Usage\r\n\r\n```python\r\nfrom surfercid import SurferCIDClient\r\nfrom surfercid.models import LTokenAccount, Status\r\n\r\n# Initialize the client\r\nclient = SurferCIDClient(api_key=\"your_api_key_here\")\r\n\r\n# Get stock information for a product\r\nstock_info = client.get_stock(\"Ltoken_create\")\r\nprint(\"Stock Info: \", stock_info)\r\n\r\n# Check account balance\r\nbalance = client.get_balance()\r\nprint(\"Balance: \", balance)\r\n\r\n# Create new LTokens\r\ncreation_order = client.create_token(quantity=1)\r\nprint(f\"Order ID: {creation_order.order_id}\")\r\n\r\n# Wait for token creation to complete\r\norder = client.get_task_status(creation_order.order_id, wait=True)\r\nif order.status == Status.SUCCESS:\r\n for account in order.accounts:\r\n if isinstance(account, LTokenAccount):\r\n print(f\"Token created: {account.to_format()}\")\r\n # Outputs: mac:XX:XX:XX:XX:XX:XX|wk:NONE0|platform:1|rid:XXX|name:XXX|cbits:1536|playerAge:25|token:XXX|vid:XXX\r\n\r\n# Example of refreshing tokens\r\nif isinstance(account, LTokenAccount):\r\n refreshed = client.refresh_token(account)\r\n print(f\"Refreshed token: {refreshed.to_format()}\")\r\n```\r\n\r\n## Available Methods\r\n\r\n### Token Creation and Management\r\n- `create_token(quantity: int = 1) -> OrderResponse`: Create new LTokens\r\n- `get_task_status(order_id: int, wait: bool = False) -> OrderResponse`: Check token creation status\r\n- `refresh_token(token_data: Union[str, LTokenAccount]) -> LTokenAccount`: Refresh an LToken\r\n\r\n### Account Management\r\n- `get_stock(product_name: str) -> Dict[str, Any]`: Get stock information for a specific product\r\n- `get_balance() -> float`: Get current account balance\r\n- `purchase(product_name: str, quantity: int) -> OrderResponse`: Purchase products\r\n- `get_order(order_id: int) -> OrderResponse`: Get details of a specific order\r\n- `get_orders(limit: Optional[int] = None) -> List[OrderResponse]`: Get list of orders\r\n\r\n## Data Models\r\n\r\n### LTokenAccount\r\n```python\r\n@dataclass\r\nclass LTokenAccount(Account):\r\n created_at: str\r\n mac: str\r\n name: str\r\n platform: str\r\n rid: str\r\n token: str\r\n wk: str = \"NONE0\"\r\n cbits: int = 1536\r\n player_age: int = 25\r\n vid: str = \"\"\r\n\r\n def to_format(self) -> str:\r\n \"\"\"Convert to the new token format\"\"\"\r\n return f\"mac:{self.mac}|wk:{self.wk}|platform:{self.platform}|rid:{self.rid}|name:{self.name}|cbits:{self.cbits}|playerAge:{self.player_age}|token:{self.token}|vid:{self.vid}\"\r\n```\r\n\r\n### OrderResponse\r\n```python\r\n@dataclass\r\nclass OrderResponse:\r\n accounts: List[Account]\r\n message: str\r\n success: bool\r\n cost: float\r\n order_id: int\r\n order_date: datetime\r\n processing: bool = False\r\n quantity: int = 0\r\n refund_amount: float = 0\r\n status: Status = Status.FAILED\r\n```\r\n\r\n### Status Enum\r\n```python\r\nclass Status(Enum):\r\n SUCCESS = \"success\"\r\n FAILED = \"failed\"\r\n PROCESSING = \"processing\"\r\n```\r\n\r\n## Error Handling\r\n\r\nThe client includes comprehensive error handling for various scenarios:\r\n\r\n```python\r\nfrom requests.exceptions import RequestException\r\n\r\ntry:\r\n # Create a new token\r\n order = client.create_token(quantity=1)\r\n status = client.get_task_status(order.order_id, wait=True)\r\n \r\n if status.status == Status.SUCCESS:\r\n print(\"Token created successfully!\")\r\n elif status.status == Status.FAILED:\r\n print(f\"Creation failed: {status.message}\")\r\n \r\nexcept RequestException as e:\r\n print(f\"API request failed: {e}\")\r\nexcept ValueError as e:\r\n print(f\"Invalid input or response: {e}\")\r\n```\r\n\r\n## Token Format\r\n\r\nThe new token format includes additional fields for enhanced functionality:\r\n```\r\nmac:XX:XX:XX:XX:XX:XX|wk:NONE0|platform:1|rid:XXX|name:XXX|cbits:1536|playerAge:25|token:XXX|vid:XXX\r\n```\r\n\r\nWhere:\r\n- `mac`: MAC address\r\n- `wk`: World key (default: NONE0)\r\n- `platform`: Platform identifier\r\n- `rid`: Resource identifier\r\n- `name`: Account name\r\n- `cbits`: Client bits (default: 1536)\r\n- `playerAge`: Player age (default: 25)\r\n- `token`: Authentication token\r\n- `vid`: Version identifier\r\n\r\n## Token Refresh Examples\r\n\r\n### Single Token Refresh\r\n```python\r\nfrom surfercid import SurferCIDClient\r\nfrom surfercid.models import LTokenAccount\r\n\r\n# Initialize client\r\nclient = SurferCIDClient(api_key=\"your_api_key\")\r\n\r\n# Create token account from formatted string\r\ntoken_str = \"mac:XX:XX:XX:XX:XX:XX|wk:NONE0|platform:1|rid:XXX|name:XXX|token:XXX\"\r\ntoken = LTokenAccount.from_format(token_str)\r\n\r\n# Refresh token\r\nrefreshed = client.refresh_token(token)\r\nprint(f\"New token: {refreshed.to_format()}\")\r\n```\r\n\r\n### Multiple Tokens Refresh\r\n```python\r\nfrom surfercid import SurferCIDClient\r\nfrom surfercid.models import LTokenAccount\r\n\r\ndef refresh_tokens(api_key: str, tokens_str: str) -> None:\r\n client = SurferCIDClient(api_key=api_key)\r\n \r\n # Parse and refresh each token\r\n for line in tokens_str.strip().split('\\n'):\r\n if not line.strip():\r\n continue\r\n \r\n try:\r\n token = LTokenAccount.from_format(line)\r\n refreshed = client.refresh_token(token)\r\n print(f\"\u2713 Refreshed {token.name}: {refreshed.to_format()}\")\r\n except Exception as e:\r\n print(f\"\u2717 Failed to refresh: {e}\")\r\n\r\n# Example usage\r\ntokens = \"\"\"\r\nmac:XX:XX:XX:XX:XX:XX|wk:NONE0|platform:1|rid:XXX|name:Token1|token:XXX\r\nmac:YY:YY:YY:YY:YY:YY|wk:NONE0|platform:1|rid:YYY|name:Token2|token:YYY\r\n\"\"\"\r\n\r\nrefresh_tokens(\"your_api_key\", tokens)\r\n```\r\n\r\nThe examples above demonstrate:\r\n1. Refreshing a single token using a formatted string\r\n2. Batch refreshing multiple tokens from a multi-line string\r\n3. Error handling for failed refreshes\r\n4. Using the key:value format for token strings\r\n",
"bugtrack_url": null,
"license": null,
"summary": "A Python client for the SurferCID API",
"version": "0.1.49",
"project_urls": {
"Homepage": "https://documenter.getpostman.com/view/15842770/2s9YJW55kQt"
},
"split_keywords": [
"surfercid",
" api",
" client",
" token"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "5b6388b57ba6430586591214e393b0ef76e7f566d892a43161afed71f6beb4a4",
"md5": "71230b7a2b052ab2ebf4b3ede143d72f",
"sha256": "bca2ca58ae3d612651bf39a1b80b4bc42ba98f6b7d3426c0f70a2d64b13b5631"
},
"downloads": -1,
"filename": "surfercid_client-0.1.49-py3-none-any.whl",
"has_sig": false,
"md5_digest": "71230b7a2b052ab2ebf4b3ede143d72f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 10652,
"upload_time": "2025-02-17T23:49:36",
"upload_time_iso_8601": "2025-02-17T23:49:36.162576Z",
"url": "https://files.pythonhosted.org/packages/5b/63/88b57ba6430586591214e393b0ef76e7f566d892a43161afed71f6beb4a4/surfercid_client-0.1.49-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "4c8478d964191244041bea3b7cf714eaffa1db7474327e65ab402a1050de6433",
"md5": "07b7be981c8db0e586d1a133b9846a28",
"sha256": "15ee94ab7aabd98f5388382c4367a9d1ed8df06caa363f63bd0bb69dfa5f3bb7"
},
"downloads": -1,
"filename": "surfercid_client-0.1.49.tar.gz",
"has_sig": false,
"md5_digest": "07b7be981c8db0e586d1a133b9846a28",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 11479,
"upload_time": "2025-02-17T23:49:37",
"upload_time_iso_8601": "2025-02-17T23:49:37.739882Z",
"url": "https://files.pythonhosted.org/packages/4c/84/78d964191244041bea3b7cf714eaffa1db7474327e65ab402a1050de6433/surfercid_client-0.1.49.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-17 23:49:37",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "surfercid-client"
}
JSON