Link and Manage Soroban Smart Account Vaults in Pay3

A Smart Account is a Soroban contract deployed on the Stellar network that acts as a dedicated USDC vault for your AI agents. Instead of giving an AI assistant direct access to your personal wallet, you deposit a controlled amount of USDC into the smart account contract. AI sessions then draw from that vault, so your primary wallet is never exposed. The contract independently enforces on-chain spending limits — meaning even if Pay3’s off-chain policy were bypassed, the contract itself would reject any transaction that violates its rules.

What a smart account contract ID looks like

Every Soroban contract is identified by a 56-character contract ID starting with the letter C:

CXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

You receive this contract ID when you deploy the Pay3 vault contract to Stellar. Keep it somewhere safe — you’ll need it to link the account and to register AI sessions on-chain.

Soroban contract functions

The Pay3 vault contract exposes the following functions:

initialize

pub fn initialize(env: Env, owner: Address, usdc_token: Address) -> Result<(), Error>

Call initialize once immediately after deploying your contract. Pass your wallet address as owner and the USDC token contract address for the network you’re using (testnet or mainnet). This function can only be called once — it permanently locks the owner address and stores the token reference.

deposit

pub fn deposit(env: Env, from: Address, amount: i128) -> Result<(), Error>

Call deposit from your owner wallet to move USDC from your wallet into the vault. The amount parameter is in stroops (1 USDC = 10,000,000 stroops). The vault balance increases immediately on confirmation.

withdraw

pub fn withdraw(env: Env, to: Address, amount: i128) -> Result<(), Error>

Call withdraw to pull USDC back out of the vault into any Stellar address you control. Only the owner address set during initialization can call this function.

add_session

pub fn add_session(
    env: Env,
    session: Address,
    expires_at: u64,
    per_tx_max: i128,
    daily_max: i128,
) -> Result<(), Error>

Call add_session to register an AI session on-chain after creating it in the dashboard. Pass the session public key as session, the expiry as a Unix timestamp, and the per-transaction and daily spending caps in stroops. Only the owner can call this function. Until you call add_session, the vault will reject any payment requests from that session.

When you create a session in the dashboard, Pay3 shows you the exact add_session parameters pre-filled — including the session public key, expiry timestamp, per-transaction maximum, and daily maximum. Copy and run them without manual calculation.

revoke_session

pub fn revoke_session(env: Env, session: Address) -> Result<(), Error>

Call revoke_session to permanently disable a specific session key on-chain. This is a one-way operation — a revoked session cannot be re-enabled. You can also revoke sessions from the dashboard, but calling revoke_session directly gives you an on-chain guarantee that is independent of Pay3’s servers.

transfer

pub fn transfer(env: Env, session: Address, to: Address, amount: i128) -> Result<(), Error>

Called by Pay3 when an AI session executes a payment. The vault checks that the session is not expired or revoked, that the amount is within per_tx_max, and that the running daily_spent total does not exceed daily_max. You never need to call transfer directly — Pay3 calls it on behalf of the session key.

get_balance

pub fn get_balance(env: Env) -> Result<i128, Error>

Returns the current USDC balance held in the vault in stroops. This is a read-only query and costs no fees.

get_session

pub fn get_session(env: Env, session: Address) -> Result<Session, Error>

Returns the on-chain record for a registered session, including its expiry, per-transaction cap, daily cap, daily spending so far, and revocation status. Use this to verify that a session was registered correctly.

How to link a smart account

Open the Sessions page

Navigate to Sessions in the dashboard navigation bar. The Link smart account form appears at the top of the page.

Paste your contract ID

Enter your full Soroban contract ID (starting with C) in the Contract ID field.

Click Link contract

Click the Link contract button. Pay3 validates the contract ID and registers it against your account. The linked contract ID appears in the list below the form (truncated for readability).

Create an AI session

Once linked, you can select this smart account when creating a new AI session. The session will draw spending allowance from this vault.

Depositing USDC into your vault

After linking, you need to fund the vault before any AI session can execute payments. Use the Stellar Laboratory, your preferred Stellar wallet app, or the Soroban CLI to call deposit:

soroban contract invoke \
  --id <YOUR_CONTRACT_ID> \
  --source <YOUR_WALLET_SECRET_KEY> \
  --network testnet \
  -- deposit \
  --from <YOUR_WALLET_ADDRESS> \
  --amount 1000000000

The example above deposits 100 USDC (100 × 10,000,000 stroops = 1,000,000,000).

You must hold a USDC trustline on your Stellar wallet before depositing. Without it, the transaction will fail with an op_no_trust error.

Managing multiple smart accounts

You can link as many smart accounts as you need — for example, one per project, one per AI assistant, or one per team member. Each smart account has its own balance and its own set of associated sessions, giving you clean budget separation.

Create one smart account per major use case. For example, link a “Coding Assistant” vault for your Cursor sessions and a separate “Research Assistant” vault for Claude sessions. This way your monthly usage table shows spending broken down by purpose.

On-chain vs. off-chain limits

Pay3 enforces spending rules at two independent layers:

Layer	Where it runs	What it controls
Off-chain policy	Pay3 servers	Daily budgets, per-tx caps, approval thresholds, allowed assets
On-chain contract	Stellar / Soroban	Absolute spending limits baked into the vault contract at session registration

The on-chain limits are set when you call add_session on your contract after creating a session in the dashboard. Even if Pay3’s off-chain systems were unavailable, the contract would still reject any transaction exceeding the registered limits.

Get Started

Core Concepts

Dashboard

MCP Integration

DeFi & Payments

Link and Manage Soroban Smart Account Vaults in Pay3

What a smart account contract ID looks like

Soroban contract functions

initialize

deposit

withdraw

add_session

revoke_session

transfer

get_balance

get_session

How to link a smart account

Depositing USDC into your vault

Managing multiple smart accounts

On-chain vs. off-chain limits

​What a smart account contract ID looks like

​Soroban contract functions

​initialize

​deposit

​withdraw

​add_session

​revoke_session

​transfer

​get_balance

​get_session

​How to link a smart account

​Depositing USDC into your vault

​Managing multiple smart accounts

​On-chain vs. off-chain limits

What a smart account contract ID looks like

Soroban contract functions

initialize

deposit

withdraw

add_session

revoke_session

transfer

get_balance

get_session

How to link a smart account

Depositing USDC into your vault

Managing multiple smart accounts

On-chain vs. off-chain limits