> ## Documentation Index
> Fetch the complete documentation index at: https://pay3.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Link a Soroban Smart Account — Pay3 Smart Accounts

> Register a deployed Soroban contract with your Pay3 account so AI sessions can use it as a spending vault. Returns the record and on-chain references.

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

**contractId** `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`

> [!NOTE]
>
> 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:

```json theme={null}
{
  "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`.

**data** `object`

The linked smart account record.

**data fields**

**data.id** `string`

Pay3 internal smart account record ID (UUID).

**data.userId** `string`

The Pay3 user ID that owns this smart account record.

**data.walletId** `string`

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

**data.contractId** `string`

The Soroban contract address, normalized to uppercase.

**data.network** `string`

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

**data.createdAt** `string`

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

**data.updatedAt** `string`

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

**data.onChain** `object`

Helpful on-chain reference values for this network environment.

**onChain fields**

**data.onChain.usdcSacContractId** `string`

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

**data.onChain.templateContractId** `string`

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

**data.onChain.initializeHint** `string`

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

**requestId** `string`

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

***

## Example

### Request

```bash theme={null}
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

```json theme={null}
{
  "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. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.