​
Accounts

There is ONE identity in Stableyard: the Account. No separate “merchant” or “developer” or “user” entity. A DopePay user sending 10toafriendandamerchantaccepting10 to a friend and a merchant accepting 1000 on their website both have the same Account structure. 
┌─────────────────────────────────────────────────┐
│                   ACCOUNT                        │
│                                                  │
│  Identity                                        │
│  ├── Wallet addresses (multiple per chain)       │
│  ├── Username → payment address (you@partner)    │
│  └── Account ID (acc_xxx)                        │
│                                                  │
│  Belongs to a Partner                            │
│  ├── alice@stableyard (default partner)          │
│  ├── alice@dopepay (DopePay partner)             │
│  └── merchant@acme (Acme partner)                │
│                                                  │
│  Settlement (user controls this)                 │
│  ├── Crypto: chain + token + wallet/vault        │
│  └── Fiat: bank/mobile (requires KYC)            │
│                                                  │
│  Modules (opt-in)                                │
│  ├── Vault → gasless payments, yield             │
│  └── KYC → fiat settlement                       │
└─────────────────────────────────────────────────┘
What you do with your Account determines your role:
  • Accept payments on your website? You’re a merchant.
  • Build an app that lets others accept payments? You’re a platform (partner).
  • Send money to a friend? You’re a user.
  • All three? Same Account, same keys.

​
How Accounts Are Created

Path 1: Dashboard (direct signup)
  Connect wallet → Account under "stableyard" partner → coffeeshop@stableyard

Path 2: Partner app (DopePay, Shopify, etc.)
  Connect wallet → Account under that partner → alice@dopepay

Path 3: First payment targeting a new wallet
  POST /v2/sessions { destination: "0xNEW_WALLET" }
  → Account auto-created under the creating partner
No approval process. No “apply for access.” Instant.

​
Partners — The Distribution Layer

Partners are platforms that build on Stableyard. Each partner gets their own namespace (@handle), API keys, and earns commission on transactions. 
┌──────────────────────────────────────────────────────────────┐
│                        PARTNER                                │
│                                                               │
│  API Keys (partner-level)                                     │
│  ├── sy_secret_* → operates across ALL accounts under partner │
│  ├── sy_pub_*    → widget/frontend for this partner           │
│  ├── sy_test_secret_* → sandbox                               │
│  └── sy_test_pub_*    → sandbox                               │
│                                                               │
│  Revenue                                                      │
│  ├── commissionBps: 50 → earns 0.5% on every transaction     │
│  └── On top of Stableyard's 25 bps base fee                  │
│                                                               │
│  Controls                                                     │
│  ├── Create sessions targeting any account                    │
│  ├── Create deposit addresses for their accounts              │
│  ├── Manage webhooks for events on their sessions             │
│  └── Cancel/refund sessions THEY created                      │
│                                                               │
│  Does NOT control                                             │
│  ├── User's settlement preferences (user controls)            │
│  ├── User's username (immutable once set)                     │
│  ├── User's wallet/vault (user controls)                      │
│  └── Other partner's sessions                                 │
└──────────────────────────────────────────────────────────────┘
Default partner: When someone signs up directly (dashboard, no app), they land under the stableyard partner with 0% commission.

​
Who Controls What

USER controls (via sy_auth_*):
├── Username (set once, immutable)
├── Settlement chain + token + destination
├── API key regeneration
├── Vault deployment + activation
└── View own sessions, ledger, settings

PARTNER controls (via sy_secret_*):
├── Create sessions targeting accounts
├── Create deposit addresses
├── Submit tx hashes on their sessions
├── Refund/cancel sessions they created
└── Webhooks for events on their sessions

NOBODY controls:
├── Primary wallet address (immutable, set at creation)
├── Account ID (auto-generated, never changes)
└── Partner assignment (account belongs to one partner)