---
title: "Sol Mate API"
description: "Stake-gated social dApp on Solana — DM, match, and meet with economic accountability"
canonical: "https://docs.ainative.studio/docs/web3/sol-mate"
last-updated: "2026-09-23T01:51:08.820Z"
---

# Sol Mate API

Source: https://docs.ainative.studio/docs/web3/sol-mate

> Stake-gated social dApp on Solana — DM, match, and meet with economic accountability

# Sol Mate API

**Base URL:** `https://solmate.ainative.studio`  
**Auth:** JWT Bearer (wallet challenge-response)  
**Chain:** Solana devnet  
**Source:** [github.com/AINative-Studio/sol-mate-trust-api](https://github.com/AINative-Studio/sol-mate-trust-api)

Sol Mate is a trust-based social dApp. Users stake USDC to DM, match, and meet. No-shows get slashed. Reputation decays with inactivity.

:::info Auth Model
Sol Mate uses **wallet-signature JWTs** — not AINative API keys. Authentication is wallet-based (Solana Ed25519 signature). AINative API keys are not accepted on protected endpoints.
:::

## Public Endpoints (No Auth Required)

These endpoints are live and accessible without any token:

| Method | Path | Description |
|--------|------|-------------|
| `POST` | `/v1/users/challenge` | Request nonce (query param) |
| `POST` | `/v1/users/onboard` | Register / login with wallet signature |
| `GET` | `/v1/rooms` | List all public rooms |
| `GET` | `/v1/rooms/discover` | Nearby rooms (lat, lng, radius_km) |
| `GET` | `/v1/rooms/{id}` | Room details |
| `GET` | `/v1/reputation/persona/{id}` | Public reputation score |
| `GET` | `/health` | Health check |

## Authentication

### 1. Request Nonce

```bash
curl -X POST "https://solmate.ainative.studio/v1/users/challenge?wallet_address=7xKXtg2..."
```

`wallet_address` is a **query parameter** (not a request body). Returns `{"nonce": "abc123", "expires_at": "..."}` — sign with your Solana wallet.

### 2. Onboard / Login

```http
POST /v1/users/onboard
Content-Type: application/json

{
  "wallet_address": "7xKXtg2...",
  "signature": "<base58-ed25519>",
  "nonce": "abc123"
}
```

Returns `{"access_token": "...", "user": {...}}`.

### 3. Use Token

```http
Authorization: Bearer <access_token>
```

All other endpoints require this wallet-issued JWT. Protected routes return `403` with no token, `401` with an invalid token.

---

## Users & Personas

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/v1/users/me` | Current user profile |
| `PATCH` | `/v1/users/me` | Update email, privacy_mode |
| `POST` | `/v1/personas` | Create persona (display_name, intent_mode, visibility_scope) |
| `GET` | `/v1/personas/me` | List my personas |
| `DELETE` | `/v1/personas/{id}` | Deactivate persona |

**intent_mode values:** `social`, `dating`, `networking`, `professional`

---

## Rooms

Geo-located social spaces. Discovery is proximity-based.

| Method | Path | Description |
|--------|------|-------------|
| `POST` | `/v1/rooms` | Create room (name, type, lat/lng, stake_required) |
| `GET` | `/v1/rooms` | List rooms (filter: type, lat, lng, radius_km) |
| `GET` | `/v1/rooms/discover` | Nearby rooms (lat, lng, radius_km required) |
| `GET` | `/v1/rooms/{id}` | Room details |
| `POST` | `/v1/rooms/{id}/join` | Join room (persona_id + stake_tx_hash) |
| `POST` | `/v1/rooms/{id}/leave` | Leave room |
| `GET` | `/v1/rooms/{id}/members` | List members |

---

## Stakes

USDC locked on Solana before interactions. Types: `dm` (0.50 USDC), `room_entry` (1.00), `meetup` (5.00).

| Method | Path | Description |
|--------|------|-------------|
| `POST` | `/v1/stakes` | Create stake (stake_type, amount_usdc, tx_hash) |
| `GET` | `/v1/stakes/me` | My active stakes |
| `POST` | `/v1/stakes/{id}/refund` | Refund stake |
| `POST` | `/v1/stakes/{id}/slash` | Slash stake (reason ≥10 chars) |
| `POST` | `/v1/escrow/meetup` | Create meetup escrow |
| `POST` | `/v1/escrow/{id}/confirm` | Confirm escrow |
| `POST` | `/v1/escrow/{id}/dispute` | Dispute escrow (reason ≥20 chars) |

**Slash amounts:** 50% first offense → +0.5x per offense (3x cap). Harassment = 100%.

---

## Matches & Messages

| Method | Path | Description |
|--------|------|-------------|
| `POST` | `/v1/matches/request` | Request match (target_persona_id, stake_id) |
| `POST` | `/v1/matches/{id}/accept` | Accept match |
| `POST` | `/v1/matches/{id}/reject` | Reject match |
| `GET` | `/v1/matches/me` | My matches (skip/limit) |
| `POST` | `/v1/messages` | Send message (match_id, content, stake_id) |
| `GET` | `/v1/messages/{match_id}` | Get message thread |

---

## Attestations

GPS-verified proof that two people met in person.

| Method | Path | Description |
|--------|------|-------------|
| `POST` | `/v1/attestations/meetup/initiate` | Start attestation (lat, lng, method) |
| `POST` | `/v1/attestations/meetup/{id}/confirm` | Counterparty confirms (token, lat, lng) |
| `POST` | `/v1/attestations/proximity` | Check proximity |
| `GET` | `/v1/attestations/me` | My attestations |

Confirmed attestations anchor an event to Hedera HCS.

---

## Reputation

5-dimension scoring with time decay.

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/v1/reputation/me` | My reputation |
| `GET` | `/v1/reputation/persona/{id}` | Persona reputation |
| `POST` | `/v1/reputation/feedback` | Submit feedback |
| `POST` | `/v1/reputation/attestation-score` | Update from attestation |

**Dimensions:** reliability, safety, response, meetup_completion, consent_confirmation

---

## Safety

| Method | Path | Description |
|--------|------|-------------|
| `POST` | `/v1/safety/report` | File safety report |
| `POST` | `/v1/safety/block` | Block user |
| `GET` | `/v1/safety/reports` | Reports against me |
| `POST` | `/v1/safety/reports/{id}/resolve` | Resolve report |

---

## AI Matchmaking

768-dim BAAI/bge-base-en-v1.5 embeddings + llama-3.3-70b for intro generation.

| Method | Path | Description |
|--------|------|-------------|
| `POST` | `/v1/ai/match-agent/preferences` | Update preferences |
| `GET` | `/v1/ai/match-agent/suggestions` | Get match suggestions |
| `POST` | `/v1/ai/match-agent/intro` | Generate intro message |
| `POST` | `/v1/ai/match-agent/filter` | Apply vibe filter |

---

## NFTs & Transfers

| Method | Path | Description |
|--------|------|-------------|
| `POST` | `/v1/nfts/mint-moment` | Mint Moment NFT (requires confirmed attestation) |
| `GET` | `/v1/nfts/moments` | My Moment NFTs |
| `POST` | `/v1/transfers` | SOL gift (recipient_wallet, amount_sol) |

---

## Full Developer Guide

See the complete guide with all request/response schemas, error codes, and rate limits:  
[`docs/WEB3_DEVELOPER_GUIDE.md`](https://github.com/AINative-Studio/sol-mate-trust-api/blob/main/docs/WEB3_DEVELOPER_GUIDE.md)

## Open Source SDKs

```bash
pip install solmate-stake-sdk    # Stake-gated access for any Solana dApp
pip install solmate-reputation   # Reputation engine + HCS anchoring
pip install solmate-x402         # x402 USDC payment middleware
```