---
title: "Derive (and persist) a smart wallet address from (owner, salt, factory)"
method: POST
path: "/wallets"
tags: ["Wallets"]
---

# Derive (and persist) a smart wallet address from (owner, salt, factory)

`POST /wallets`

Idempotent "ensure exists". Returns the deterministic CREATE2-derived
address. POST (not GET) because it persists a wallet record server-side
as a side effect of the derivation. Authorize with a user Bearer JWT
**or** a partner assertion (`scope: read`) whose `sub` is the owner EOA.

## Request body

- CreateWalletRequest
  - `salt` string, required — Salt as a decimal string (big-int). Determines the derived address together with the factory.
  - `factoryAddress` string — Lowercase or checksummed hex EOA / contract address.
  - `chainId` integer — Numeric chain ID (e.g. 11155111 for Sepolia, 8453 for Base). On chain-aware trigger/node configs this is required and must be a configured chain; on query/filter params it is optional.

## Response `200`

Wallet derived (existing record returned if already present).

- Wallet
  - `address` string, required — Lowercase or checksummed hex EOA / contract address.
  - `salt` string, required — Salt used in CREATE2 derivation (decimal string).
  - `factoryAddress` string — Lowercase or checksummed hex EOA / contract address.
  - `isHidden` boolean
  - `totalWorkflowCount` integer
  - `enabledWorkflowCount` integer
  - `completedWorkflowCount` integer
  - `failedWorkflowCount` integer
  - `disabledWorkflowCount` integer

## Other responses

- `201` — Wallet derived (new record persisted).
- `400` — Request validation failed.
- `401` — Missing or invalid bearer token.

## Changes

> 16 revisions in range; 6 could not be searched.

- **2026-06-05** `d080cab4deb6` — 1 info
  - added the new optional request property `chainId`
- **2026-06-04** `298db67c81a9` — 1 warning
  - removed the request property `chainId`

[Change history](https://skmtc.dev/avaprotocol/apis/ava-protocol-avs-api/changes/wallets/post.md)

---

[API](https://skmtc.dev/avaprotocol/apis/ava-protocol-avs-api.md) · [All operations](https://skmtc.dev/avaprotocol/apis/ava-protocol-avs-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/avaprotocol/ava-protocol-avs-api/revisions/841dc6a5d532/schema)