Link a Soroban Smart Account — Pay3 Smart Accounts

Before an AI session can make on-chain payments on your behalf, you must link a deployed Soroban smart account contract to your Pay3 account. This endpoint creates that association — it does not deploy the contract itself, but records your contract’s address so Pay3 AI sessions can reference it as a spending vault and apply your spending policies. If the contract address has already been linked by the same user, the record is updated rather than duplicated.

Endpoint

POST /api/smart-accounts Authentication is required. Include either the pay3_session cookie or an Authorization: Bearer <session-token> header.

Request Body

string

required

The Soroban contract address to link — a 56-character Stellar address beginning with C. The address is case-insensitive and will be normalized to uppercase.Example: CDJT5OQNBBSXMFBKXH3ZHQJH3XPXKBQQMYIBNHQK5ZYXDV7KXQHRMTE

The contract must already be deployed and initialized on Stellar before you link it here. Pay3 expects the contract to have been set up by calling initialize(owner, usdc_token) with your wallet as the owner and the correct USDC SAC contract ID as the token. Linking an uninitialized contract will succeed at the API level but may cause failures when AI sessions attempt to use it.

Response

All Pay3 API responses are wrapped in a standard envelope:

{
  "data": { ... },
  "requestId": "req_01hx2q3r4s5t6u7v8w9x0y1z"
}

A successful 201 Created response returns the newly created (or updated) smart account record, along with on-chain reference values, inside data.

object

The linked smart account record.

Hide data fields

string

Pay3 internal smart account record ID (UUID).

string

The Pay3 user ID that owns this smart account record.

string

The Pay3 wallet record ID this smart account is associated with.

string

The Soroban contract address, normalized to uppercase.

string

The Stellar network this contract was registered under — TESTNET or PUBLIC, derived from your current session’s network.

string

ISO 8601 timestamp of when this smart account was first linked.

string

ISO 8601 timestamp of when this smart account record was last updated.

object

Helpful on-chain reference values for this network environment.

Show onChain fields

string

The USDC Stellar Asset Contract (SAC) address for this network. Use this as the usdc_token argument when calling initialize() on your contract.

string

The Pay3 reference smart account template contract ID used during deployment.

string

A human-readable reminder of the initialization sequence for a new contract.

string

A unique identifier for this API request, useful for support and debugging.

Example

Request

curl --request POST \
  --url https://api.pay3.dev/api/smart-accounts \
  --header 'Authorization: Bearer your-session-token-here' \
  --header 'Content-Type: application/json' \
  --data '{
    "contractId": "CDJT5OQNBBSXMFBKXH3ZHQJH3XPXKBQQMYIBNHQK5ZYXDV7KXQHRMTE"
  }'

Response Body

{
  "data": {
    "id": "e7f8a9b0-c1d2-3456-7890-abcdef123456",
    "userId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "walletId": "f0e1d2c3-b4a5-6789-0123-456789abcdef",
    "contractId": "CDJT5OQNBBSXMFBKXH3ZHQJH3XPXKBQQMYIBNHQK5ZYXDV7KXQHRMTE",
    "network": "TESTNET",
    "createdAt": "2024-11-01T10:30:00.000Z",
    "updatedAt": "2024-11-01T10:30:00.000Z",
    "onChain": {
      "usdcSacContractId": "CBIELTK6YBZJU5UP2WWQEUCYKLPU6AUNZ2BQ4WWFEIE3USCIHMXQDAMA",
      "templateContractId": "CCWAMYJME4H5CKG7OLXGC2T4M7FQGKWH3Y7TMKHBRVNLG6ZQPQHXJDE",
      "initializeHint": "Deploy contracts/smart-account, then invoke initialize(owner, usdc_token) before deposit/add_session."
    }
  },
  "requestId": "req_01hx2q3r4s5t6u7v8w9x0y1z"
}

Error Responses

HTTP Status	Description
`400 Bad Request`	`contractId` is missing, empty, or not a valid 56-character Stellar address beginning with `C`.
`401 Unauthorized`	Missing or invalid session.
`404 Not Found`	No wallet record found for the authenticated user.

Authentication

Wallet & Accounts

Sessions & Policies

Transactions

Contacts & Analytics

Link a Soroban Smart Account — Pay3 Smart Accounts

Endpoint

Request Body

Response

Example

Request

Response Body

Error Responses

​Endpoint

​Request Body

​Response

​Example

​Request

​Response Body

​Error Responses

Endpoint

Request Body

Response

Example

Request

Response Body

Error Responses