Contacts API — List, Create, and Delete Recipients

Contacts are your saved Stellar recipients — the trusted addresses your AI agents resolve by name when initiating transfers. Instead of requiring a raw Stellar address on every payment instruction, you can register a contact with a human-readable alias (e.g. alice) and let Pay3’s AI resolve it automatically at transaction time. This page documents all three contact management endpoints: listing your existing contacts, creating a new one, and deleting one you no longer need.

Authentication

All requests must include a valid bearer token in the Authorization header, or a pay3_session cookie obtained during wallet authentication.

Authorization: Bearer <token>

GET /api/contacts

Retrieve the full list of contacts saved to your account. Contacts are returned in ascending alphabetical order by displayName.

Endpoint

GET /api/contacts

Response fields

string

required

Unique UUID identifying this contact.

string

required

Human-readable name for the contact (e.g. "Alice Johnson").

string

Short identifier used by the AI to resolve this recipient by name (e.g. "alice"). May be null if no alias was set at creation.

string

required

The contact’s Stellar public key (G-address), stored in uppercase.

string

required

ISO 8601 timestamp marking when the contact was verified. Set to the creation time automatically.

string

required

ISO 8601 timestamp when the contact was created.

string

required

ISO 8601 timestamp when the contact was last modified.

Example request

curl https://api.pay3.dev/api/contacts \
  -H "Authorization: Bearer <token>"

Example response

[
  {
    "id": "c1a2b3d4-0001-4abc-8def-000000000001",
    "displayName": "Alice Johnson",
    "alias": "alice",
    "stellarAddress": "GDQP2KPQGKIHYJGXNUIYOMHARUARCA7DJT5FO2FFOOKY3B2WSQHG4W37",
    "verifiedAt": "2025-06-01T10:00:00.000Z",
    "createdAt": "2025-06-01T10:00:00.000Z",
    "updatedAt": "2025-06-01T10:00:00.000Z"
  },
  {
    "id": "c1a2b3d4-0002-4abc-8def-000000000002",
    "displayName": "Bob Smith",
    "alias": "bob",
    "stellarAddress": "GBVFEQKQ5VGHIH4CVXOL5TXIVMS6OJQMQHM5LLNTV3AAJHID5OFWKM4",
    "verifiedAt": "2025-06-15T08:30:00.000Z",
    "createdAt": "2025-06-15T08:30:00.000Z",
    "updatedAt": "2025-06-15T08:30:00.000Z"
  }
]

POST /api/contacts

Create a new contact and associate it with your account. The stellarAddress is normalized to uppercase on save, and verifiedAt is set automatically to the time of creation. Returns 201 Created with the new contact object.

Endpoint

POST /api/contacts

Request body

string

required

Full human-readable name for the contact (e.g. "Alice Johnson"). Leading and trailing whitespace is stripped automatically.

string

Short identifier used by the Pay3 AI to resolve this recipient by name during payment instructions (e.g. "alice"). Must be unique across all your contacts. Omit to leave the alias unset.

string

required

The contact’s Stellar public key (G-address). Whitespace is stripped and the value is converted to uppercase before storage.

The alias field must be unique across all your contacts. When an AI agent receives a natural-language instruction like “send 50 USDC to alice”, Pay3 resolves the recipient by matching alias against your contact list. Duplicate aliases will cause resolution to fail.

Response fields

string

required

Unique UUID assigned to the newly created contact.

string

required

The display name as stored (whitespace trimmed).

string

The alias as stored, or null if none was provided.

string

required

The Stellar G-address, normalized to uppercase.

string

required

ISO 8601 timestamp marking when the contact was verified. Set to the creation time automatically.

string

required

ISO 8601 timestamp when the contact record was created.

string

required

ISO 8601 timestamp when the contact was last modified. Equals createdAt on creation.

Error responses

Status	Meaning
`400 Bad Request`	Missing `displayName` or `stellarAddress`, or a duplicate `alias` already exists on your account.
`401 Unauthorized`	Missing or invalid bearer token.
`409 Conflict`	A contact with the same `stellarAddress` already exists on your account.

Example request

curl -X POST https://api.pay3.dev/api/contacts \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "Alice Johnson",
    "alias": "alice",
    "stellarAddress": "GDQP2KPQGKIHYJGXNUIYOMHARUARCA7DJT5FO2FFOOKY3B2WSQHG4W37"
  }'

Example response

{
  "id": "c1a2b3d4-0001-4abc-8def-000000000001",
  "displayName": "Alice Johnson",
  "alias": "alice",
  "stellarAddress": "GDQP2KPQGKIHYJGXNUIYOMHARUARCA7DJT5FO2FFOOKY3B2WSQHG4W37",
  "verifiedAt": "2025-07-08T14:30:00.000Z",
  "createdAt": "2025-07-08T14:30:00.000Z",
  "updatedAt": "2025-07-08T14:30:00.000Z"
}

DELETE /api/contacts/:id

Permanently delete a contact from your account by its UUID. This action is irreversible — the contact record is removed immediately and cannot be recovered. Returns HTTP 204 No Content on success.

Endpoint

DELETE /api/contacts/:id

Path parameters

string

required

The UUID of the contact to delete. You can only delete contacts belonging to your own account.

If a contact’s id appears in a policy’s allowedRecipientIds list, deleting the contact does not automatically remove it from that list. Any active AI session governed by that policy will continue to reference the now-deleted contact ID. Update the affected policies after deleting a contact to keep your recipient restrictions accurate.

Response

Returns HTTP 204 No Content on success — no response body is sent.

Error responses

Status	Meaning
`400 Bad Request`	The provided `id` is not a valid UUID.
`401 Unauthorized`	Missing or invalid bearer token.
`404 Not Found`	No contact exists for the given `id` on your account.

Example request

curl -X DELETE https://api.pay3.dev/api/contacts/c1a2b3d4-0001-4abc-8def-000000000001 \
  -H "Authorization: Bearer <token>"

Authentication

Wallet & Accounts

Sessions & Policies

Transactions

Contacts & Analytics

Contacts API — List, Create, and Delete Recipients

Authentication

GET /api/contacts

Endpoint

Response fields

Example request

Example response

POST /api/contacts

Endpoint

Request body

Response fields

Error responses

Example request

Example response

DELETE /api/contacts/:id

Endpoint

Path parameters

Response

Error responses

Example request

​Authentication

​GET /api/contacts

​Endpoint

​Response fields

​Example request

​Example response

​POST /api/contacts

​Endpoint

​Request body

​Response fields

​Error responses

​Example request

​Example response

​DELETE /api/contacts/:id

​Endpoint

​Path parameters

​Response

​Error responses

​Example request

Authentication

GET /api/contacts

Endpoint

Response fields

Example request

Example response

POST /api/contacts

Endpoint

Request body

Response fields

Error responses

Example request

Example response

DELETE /api/contacts/:id

Endpoint

Path parameters

Response

Error responses

Example request