Quickstart

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/{wallet_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.

The first call you make is POST, not GET. GET /v0/user/me returns 404 USR-404-001 until the user is created — it does not auto-provision. If you see a 404 on the first request, follow it with POST /v0/user/ rather than retrying the GET.

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.

Background Safe deployment is the default ai_agent cohort behaviour. Environments configured for user-signed Safe deploy (recommended for partners who want user-controlled wallets) or BYO Safe (existing on-chain Safe) follow a different onboarding step instead. See Onboarding cohorts.

Supported `chain_id` values

chain_id follows EIP-155 and must be one of Sumvin’s supported EVM networks:

`chain_id`	Network	Type
`1`	Ethereum Mainnet	mainnet
`10`	Optimism	mainnet
`56`	BNB Smart Chain	mainnet
`137`	Polygon	mainnet
`8453`	Base	mainnet
`42161`	Arbitrum One	mainnet
`43114`	Avalanche C-Chain	mainnet
`1329`	Sei	mainnet
`1328`	Sei Testnet	testnet

The example below uses 1329 (Sei). Pass any value from the table — Sumvin deploys the user’s Safe on the chain you specify.

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
  }'

const res = await fetch("https://api.sumvin.com/v0/user/", {
  method: "POST",
  headers: {
    "x-juno-jwt": process.env.SUMVIN_JWT!,
    "x-juno-orgid": process.env.SUMVIN_ORG_ID!,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    primary_eoa_address: "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD78",
    chain_id: 1329,
  }),
});
const user = await res.json();

import httpx
import os

res = httpx.post(
    "https://api.sumvin.com/v0/user/",
    headers={
        "x-juno-jwt": os.environ["SUMVIN_JWT"],
        "x-juno-orgid": os.environ["SUMVIN_ORG_ID"],
    },
    json={
        "primary_eoa_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD78",
        "chain_id": 1329,
    },
)
user = res.json()

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" }
  }
}

`safe_creation_status` values

The Safe smart wallet is deployed by a background worker after the user record is created. Poll GET /v0/user/me to watch this field transition.

Value	Meaning	What the UI should show
`pending`	Initial state — Safe creation has been queued but not yet picked up by the worker.	Brief; treat the same as `processing`.
`processing`	Worker is deploying the Safe contract on-chain.	”Setting up your wallet…” with a spinner. Continue polling.
`completed`	Safe deployed. `primary_smart_wallet_address` is now populated.	Reveal the smart-wallet-dependent surfaces (transactions, cards).
`failed`	Deployment failed and will not retry automatically.	Surface a contact-support path. Do not block onboarding on this field — `phone_verification` and `kyc_verification` proceed independently.

Treat pending and processing as the same non-terminal state. completed and failed are terminal — once you observe one, stop polling this field.

When the user already exists — `208 Already Reported`

If the authenticated identity already maps to a Sumvin user, POST /v0/user/ returns 208 Already Reported with the existing record. The body is the same UserResponse shape as the 201 Created response above — same user object, same _links, no slim variant. This means you can call POST /v0/user/ idempotently from your onboarding entry point without checking for duplicates first.

Error responses

All errors follow the RFC 7807 Problem Details format. The three you should design UI for:

401 Unauthorized — missing or invalid JWT

{
  "type": "https://api.sumvin.com/errors/usr-401-001",
  "title": "User Authentication Failed",
  "status": 401,
  "detail": "Missing or invalid x-juno-jwt header.",
  "instance": "/v0/user",
  "error_code": "USR-401-001",
  "trace_id": "abc-123-def"
}

The x-juno-jwt header is missing, malformed, or expired. Refresh the token from your auth provider and retry.

422 Unprocessable Entity — bad payload

Returned when FastAPI rejects the request body before it reaches the handler — for example, a non-integer chain_id, a missing required field, or an invalid email shape.

{
  "detail": [
    {
      "type": "int_parsing",
      "loc": ["body", "chain_id"],
      "msg": "Input should be a valid integer, unable to parse string as an integer",
      "input": "sei"
    }
  ]
}

Fix the field at loc and retry. This response uses FastAPI’s default validation error envelope, not RFC 7807 — it is the one place in the user-creation flow where the shape differs.

208 Already Reported — user exists for this JWT

Not strictly an error — Sumvin returns 208 to signal an idempotent replay rather than 409 Conflict. The body is the existing user record (see above).

{
  "user": {
    "id": "usr_abc123",
    "primary_eoa_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD78",
    "safe_creation_status": "completed",
    "email": "user@example.com",
    "created_at": 1740000000000,
    "updated_at": 1740000050000
  },
  "_links": {
    "self": { "href": "/v0/user/me" },
    "wallets": { "href": "/v0/wallets" },
    "kyc-status": { "href": "/v0/kyc/status" }
  }
}

Treat 201 and 208 as the same success path — the record is yours either way.

Other status codes worth handling defensively: 400 WAL-400-001 if primary_eoa_address is not a valid EVM address, and 403 WAL-403-003 if the address cannot be verified against your auth provider’s connected identity. Both follow the RFC 7807 shape shown above.

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/onboarding/steps" \
  -H "x-juno-jwt: <your-jwt-token>" \
  -H "x-juno-orgid: <your-org-id>"

Response: 200 OK

{
  "onboarding": {
    "current_step": "phone_verification",
    "is_complete": false,
    "steps": [
      { "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 }
    ]
  },
  "_links": {
    "self": { "href": "/v0/user/me/onboarding/steps" },
    "onboarding-events": { "href": "/v0/user/me/onboarding/events" }
  }
}

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.

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"
  }'

const res = await fetch("https://api.sumvin.com/v0/wallets/", {
  method: "POST",
  headers: {
    "x-juno-jwt": process.env.SUMVIN_JWT!,
    "x-juno-orgid": process.env.SUMVIN_ORG_ID!,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ credential_id: "cred_abc123" }),
});
const wallet = await res.json();

import httpx
import os

res = httpx.post(
    "https://api.sumvin.com/v0/wallets/",
    headers={
        "x-juno-jwt": os.environ["SUMVIN_JWT"],
        "x-juno-orgid": os.environ["SUMVIN_ORG_ID"],
    },
    json={"credential_id": "cred_abc123"},
)
wallet = res.json()

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.

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>"

const res = await fetch("https://api.sumvin.com/v0/wallets/wal-a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4/assets", {
  headers: {
    "x-juno-jwt": process.env.SUMVIN_JWT!,
    "x-juno-orgid": process.env.SUMVIN_ORG_ID!,
  },
});
const assets = await res.json();
console.log(assets);

import httpx
import os

res = httpx.get(
    "https://api.sumvin.com/v0/wallets/wal-a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4/assets",
    headers={
        "x-juno-jwt": os.environ["SUMVIN_JWT"],
        "x-juno-orgid": os.environ["SUMVIN_ORG_ID"],
    },
)
print(res.json())

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.

Minting a public RPC key

If your integration calls the RPC endpoint from a browser or mobile bundle, mint a public-partition key with rpc.invoke. Public-partition keys are scoped to a single namespace (rpc.*) and are safe to ship in client-side code.

curl -X POST https://api.sumvin.com/v0/organisation/<org_id>/keys \
  -H "x-juno-jwt: <your-jwt-token>" \
  -H "x-juno-orgid: <org-id>:<env-id>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "browser-rpc-key",
    "env_id": "<env-id>",
    "scopes": ["rpc.invoke"]
  }'

The response carries partition: "public", scopes: ["rpc.invoke"], and a _links.rpc_docs HAL link pointing at the RPC method reference. All requests authenticate with the returned key via Authorization: Bearer:

curl <rpc-endpoint>/<method> \
  -H "Authorization: Bearer <returned-key>"

The RPC method catalogue is documented separately. Use _links.rpc_docs from the create response to find the latest method list.

For the server-side flow (full sis.* scope set) and the partition / scope reference, see SIS scopes & partitions.

What’s next

Next	Where	When
Full account flow	Stand up an account	Before putting real users through KYC and Safe deployment
Auth reference	Authentication	When you’re wiring up your JWT provider or SIS key
API conventions	API conventions	When a response shape surprises you — HAL, 7807, expand, 202 patterns
Wallet depth	Wallets guide	When you need multi-chain or manual Safe flows
SIS RPC keys	Authentication → Scopes & partitions	When you need a public-safe key for a browser or mobile bundle

Introduction

Quickstarts

Guides

Product Guides

API Reference

Prerequisites

Supported `chain_id` values

`safe_creation_status` values

When the user already exists — `208 Already Reported`

Error responses

Minting a public RPC key

What’s next

​Prerequisites

​Supported chain_id values

​safe_creation_status values

​When the user already exists — 208 Already Reported

​Error responses

​Minting a public RPC key

​What’s next

Prerequisites

Supported `chain_id` values

`safe_creation_status` values

When the user already exists — `208 Already Reported`

Error responses

Minting a public RPC key

What’s next