Skip to main content
At the end of this page, you will have created a Sumvin user, added a wallet, and made a real call to: GET /v0/wallets/{id}/assets — Returns a JSON body listing the wallet’s balances with _links for navigation. Nothing here is a toy. The call you make in five minutes is the call you run in production.

​
Prerequisites

  • A Platform API JWT from your configured auth provider (Dynamic Labs, Privy, or ). See Authentication.
  • Your platform’s base URL — https://api.sumvin.com/v0.
  • A wallet address for the user () on Sei (chain_id: 1329).
  • Your x-juno-orgid if your credentials span multiple Sumvin organisations (see Authentication). Single-org integrations can omit this header.
The Platform API uses the x-juno-jwt header (no Bearer prefix). Reserve Authorization: Bearer for SIS API calls. Multi-tenant callers also pass x-juno-orgid: <your-org-id> to scope the request to a specific organisation.
1

Create the user

Register the user with their primary EOA address. Sumvin queues a Safe smart account for deployment on the specified chain in the background — you do not wait for it here.
curl -X POST https://api.sumvin.com/v0/user/ \
  -H "x-juno-jwt: <your-jwt-token>" \
  -H "x-juno-orgid: <your-org-id>" \
  -H "Content-Type: application/json" \
  -d '{
    "primary_eoa_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD78",
    "chain_id": 1329
  }'
Response: 201 Created
{
  "user": {
    "id": "usr_abc123",
    "username": null,
    "first_name": null,
    "last_names": null,
    "auth_provider": "dynamic",
    "auth_provider_id": "dyn_xxxxxxxxxx",
    "primary_eoa_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD78",
    "primary_smart_wallet_address": null,
    "safe_creation_status": "processing",
    "email": "user@example.com",
    "phone": null,
    "phone_verified_at": null,
    "created_at": 1740000000000,
    "updated_at": 1740000000000,
    "deleted_at": null,
    "profile_picture_url": null
  },
  "_links": {
    "self": { "href": "/v0/user/me" },
    "wallets": { "href": "/v0/wallets" },
    "kyc-status": { "href": "/v0/kyc/status" }
  }
}
If the user already exists, you get 208 Already Reported with the existing record.
2

Check onboarding status

The onboarding state machine tells you which step the user is on. is_complete: true gates the next step.
curl "https://api.sumvin.com/v0/user/me?expand=onboarding" \
  -H "x-juno-jwt: <your-jwt-token>" \
  -H "x-juno-orgid: <your-org-id>"
Response: 200 OK
{
  "user": {
    "id": "usr_abc123",
    "primary_eoa_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD78",
    "primary_smart_wallet_address": null,
    "safe_creation_status": "processing"
  },
  "onboarding": {
    "current_step": "phone_verification",
    "is_complete": false,
    "steps": [
      { "step": "created", "status": "completed", "gated": false, "meta": null },
      { "step": "phone_verification", "status": "current", "gated": false, "meta": null },
      { "step": "kyc_verification", "status": "pending", "gated": false, "meta": null },
      { "step": "open_banking", "status": "pending", "gated": false, "meta": null },
      { "step": "card_setup", "status": "pending", "gated": false, "meta": null },
      { "step": "feature_selection", "status": "pending", "gated": false, "meta": null },
      { "step": "complete", "status": "pending", "gated": false, "meta": null }
    ]
  },
  "_links": {
    "self": { "href": "/v0/user/me" },
    "kyc-status": { "href": "/v0/kyc/status" }
  }
}
The server drives the transitions — you submit the prompted data for each step until is_complete is true. See the onboarding guide for the full flow, including phone and KYC.
3

Add a wallet

Once onboarding completes, add the user’s wallet. If you use Dynamic Labs, pass the credential_id from the user’s verified credential — Sumvin resolves the address and chain from Dynamic’s API.
curl -X POST https://api.sumvin.com/v0/wallets/ \
  -H "x-juno-jwt: <your-jwt-token>" \
  -H "x-juno-orgid: <your-org-id>" \
  -H "Content-Type: application/json" \
  -d '{
    "credential_id": "cred_abc123"
  }'
Response: 201 Created
{
  "id": "wal-a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
  "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD78",
  "chain_id": 1329,
  "is_primary": true,
  "is_eoa": true,
  "nickname": null,
  "logo_uri": null,
  "created_at": 1740000001000,
  "deleted_at": null,
  "_links": {
    "self": { "href": "/v0/wallets/wal-a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4" },
    "user": { "href": "/v0/user/me" }
  }
}
For auth providers that do not issue credential IDs, use the SIWE challenge/verify flow instead — see the wallets guide for all three ownership verification methods.
4

Query wallet balances

This is the working artefact. The response lists token balances with USD valuations, plus HAL _links to navigate to the wallet itself and set-primary action.
curl https://api.sumvin.com/v0/wallets/wal-a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4/assets \
  -H "x-juno-jwt: <your-jwt-token>" \
  -H "x-juno-orgid: <your-org-id>"
Response: 200 OK
{
  "wallet_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD78",
  "wallet_chain_id": 1329,
  "assets": [
    {
      "symbol": "ETH",
      "name": "Ether",
      "chain_id": 1329,
      "balance": "0.05423100",
      "balance_usd": "173.54",
      "balance_updated_at": 1740000010000,
      "transactions_href": "/v0/wallets/wal-a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4/assets/eth-1329/transactions",
      "_links": {
        "self": { "href": "/v0/wallets/wal-a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4/assets" }
      }
    }
  ],
  "total_assets": 1,
  "_links": {
    "self": { "href": "/v0/wallets/wal-a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4/assets" },
    "wallet": { "href": "/v0/wallets/wal-a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4" }
  }
}
You have a live Sumvin integration. The _links field is how every response advertises its next actions — use them instead of hardcoding URLs.

​
What’s next

NextWhereWhen
Full account flowStand up an accountBefore putting real users through KYC and Safe deployment
Auth referenceAuthenticationWhen you’re wiring up your JWT provider or SIS key
API conventionsAPI conventionsWhen a response shape surprises you — HAL, 7807, expand, 202 patterns
Wallet depthWallets guideWhen you need multi-chain or manual Safe flows