Skip to main content
POST
/
v0
/
user
/
me
/
onboarding
/
safe
Submit Onboarding Safe
curl --request POST \
  --url https://api.sumvin.com/v0/user/me/onboarding/safe \
  --header 'Content-Type: application/json' \
  --header 'x-sumvin-pat: <api-key>' \
  --data '
{
  "address": "0x000000000000000000000000000000000000dead"
}
'
{
  "_links": {},
  "config": {
    "mode": "user_signed_deploy",
    "chain_id": 123,
    "entrypoint": "<string>",
    "user_operation": {},
    "user_op_hash": "<string>",
    "predicted_safe_address": "<string>",
    "user_eoa": "<string>",
    "sponsorship_expires_at_ms": 123,
    "salt_nonce": 123
  },
  "required": true,
  "wallet": {
    "id": "<string>",
    "address": "<string>",
    "chain_id": 123,
    "is_primary": true,
    "is_eoa": true,
    "created_at": 123,
    "nickname": "<string>",
    "logo_uri": "<string>",
    "deleted_at": 123,
    "cards": [
      {
        "id": "<string>",
        "last_four": "<string>",
        "brand": "<string>",
        "exp_month": 123,
        "exp_year": 123,
        "cardholder_name": "<string>",
        "card_type": "<string>",
        "is_primary": true,
        "linked_wallet_address": "<string>",
        "created_at": 123,
        "current_status": {
          "status": "<string>",
          "sub_status": "<string>",
          "changed_by": "<string>",
          "created_at": 123
        }
      }
    ]
  },
  "chain_id": 123
}

Authorizations

x-sumvin-pat
string
header
required

Personal access token issued to the Sumvin CLI. Send it in the x-sumvin-pat header to authenticate as the owning user.

Headers

Idempotency-Key
string | null

Optional idempotency key. Retrying the same request with the same key returns the original cached response. Reusing a key with a different request body returns 409 Conflict. Cached for 24h.

Maximum string length: 255
x-sumvin-token
string | null
x-sumvin-pat
string | null
x-juno-jwt
string | null
x-juno-orgid
string | null

Tenant org ID for multi-tenant auth

X-Timestamp-Format
string

Controls how timestamp fields are serialized in JSON response bodies.

Default (header omitted or any other value): epoch milliseconds as integers. iso8601: UTC ISO 8601 strings of the form YYYY-MM-DDTHH:MM:SSZ.

Example: with X-Timestamp-Format: iso8601, the field value 1704067200000 becomes "2024-01-01T00:00:00Z".

Affected fields (recursively, in dicts and arrays): any field whose name ends in _at, plus the literal field names timestamp, period_start, and period_end. All other fields are passed through unchanged.

Only iso8601 is recognized. Any other value (or omitting the header) yields the default epoch-ms representation; the server does not reject unknown values, so this is documented as an example rather than an enum to keep generated clients permissive.

Example:

"iso8601"

Body

application/json

Submission payload for the Bring-Your-Own-Safe cohort.

Pydantic narrows by required field — the presence of address selects this variant of the request body union.

address
string
required

EVM address of the existing Safe. The service layer enforces format validation (regex) and verifies the contract on-chain.

Example:

"0x000000000000000000000000000000000000dead"

Response

Submission accepted for the byo cohort; the response carries the post-mutation Safe state.

Response for GET/POST /v0/user/me/onboarding/safe.

The mode field selects which Safe-onboarding flow applies to the user. The config field always carries the cohort-specific data the client needs to render or complete the step — its shape matches mode (clients switch once on config.mode and read inner fields, which may be null when no work is currently prepared). The wallet field is populated once the Safe has been persisted; null otherwise.

HAL-style hypermedia links for navigation and available actions.

mode
enum<string>
required

Which Safe-onboarding flow applies. 'user_signed_deploy' when the user signs the deploy UserOp; 'byo' when the user submits an existing Safe address; 'agent_create2' when the agent signer workflow handles deployment.

Available options:
user_signed_deploy,
byo,
agent_create2
config
UserSignedDeployData · object
required

Cohort config for a user signing a CREATE2 deploy UserOp themselves.

The chain ID is the user's onboarding-selected primary chain; null when the user has not yet selected one (e.g., partway through onboarding before chain selection is persisted). The envelope fields (predicted Safe address, prepared UserOp, paymaster sponsorship) are populated only after the server has prepared a fresh sponsored UserOp; they are null when no work is currently prepared (e.g., before the user reaches the step or while a previous prepare is still in flight). The signature field on user_operation is empty — clients sign and re-submit.

required
boolean
required

True when the user still needs to act on this step. False once the step is completed, skipped, or does not apply to this user.

step_status
enum<string>
required

Status of this onboarding step.

Available options:
completed,
submitted,
current,
pending,
skipped
wallet
WalletData · object

Persisted Safe wallet. Populated once the wallet row exists (PENDING for user-signed-deploy after submit; COMPLETED for BYO; set by the signer workflow for agent_create2). Null otherwise.

chain_id
integer | null

Chain ID on which the Safe must reside. Null when the user has not yet selected a primary chain (e.g., partway through onboarding before chain selection is persisted).