Create a User and Wallet Account

TIP

Complete the wallet_request setup in the Wallet tutorial first, then run the examples in that same shell.

An OOLIN USER account represents the customer's wallet balance and owns its deposit addresses, withdrawals, and ledger entries. Use a stable customer identifier in uid.

Verify connectivity and server time

The health and time endpoints do not require authentication.

curl -sS "$WALLET_BASE_URL/health" | jq
curl -sS "$WALLET_BASE_URL/time" | jq

/health confirms the process is reachable; it does not guarantee that every database or chain dependency is healthy. Also make one authenticated business request during readiness checks. Keep the caller time within five minutes of the server time.

Look up an existing account

POST /accounts is not idempotent. Query by uid before creating another account.

export CUSTOMER_UID='user-tutorial-001'
wallet_request GET "/users/$CUSTOMER_UID/accounts" | jq

Reuse the intended active USER account when it already exists.

export ACCOUNT_ID='{existing-active-user-account-id}'

Replace the placeholder with the returned ID and skip creation below. When several accounts exist, use your persisted customer mapping to choose one. Investigate a locked or disabled account rather than creating another account to bypass its state.

Create the customer account

Run this only when the intended account is absent. If the create response is lost, query the account list for the same uid again before considering another create request.

account_body="$(jq -nc \
  --arg uid "$CUSTOMER_UID" \
  '{uid:$uid,account_type:"USER",metadata:{source:"wallet-tutorial"}}')"

account_response="$(wallet_request POST '/accounts' "$account_body")"
printf '%s\n' "$account_response" | jq

export ACCOUNT_ID="$(printf '%s' "$account_response" | jq -r '.data.account_id')"
wallet_request GET "/accounts/$ACCOUNT_ID" | jq

Persist CUSTOMER_UID and ACCOUNT_ID together. Validate the returned account_type and status before enabling deposits or withdrawals.

Operational rules

• Do not expose ACCOUNT_ID as proof of customer identity; authorize requests in your own backend.
• Prevent concurrent account-creation requests for the same customer.
• Store customer-to-account mapping transactionally.
• Treat a locked or inactive account as unavailable for new fund movements.

Next: Issue a deposit address.