Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.agentity.to/llms.txt

Use this file to discover all available pages before exploring further.

An identity is a set of real-world credentials provisioned for a single AI agent. Each identity is keyed to an agentId string you define — a unique identifier for the agent within your account.

​
What makes up an identity

When you call create_agent_identity, Agentity provisions the channels you request and returns their credentials in a single response.
ChannelProviderReturned fieldsRequired
EmailAgentMailemailAddress, emailIdNo
PhoneAgentPhonephoneNumber, phoneNumberIdNo
Virtual cardPrivacy.compan, cvv, exp_year, exp_month, tokenNo
Crypto WalletEthereumcryptoAddress
network		No
Each channel is optional. You can provision any combination — or none at all. Support for more providers is coming soon.

​
Email

A real inbox provisioned by the chosen provider. Agentity stores the emailAddress and emailId so you can look them up later.

​
Phone

An SMS-capable phone number. Agentity stores the phoneNumber.

​
Virtual card

A virtual payment card. Agentity stores only the token — a stable reference to the card at the provider. Depending on provider, the full card details (pan, cvv, exp_year, exp_month) are only shared once at agent creation. You may want to have your agent immediately store the details in its vault.

​
Crypto Wallet

A network-specific crypto wallet. Agentity stores the address and the private key (which is encrypted). The agent can get the wallet’s balance and send crypto to different addresses on the same network.

​
Shell identities

You can create an identity with no channels by omitting email, phone, virtualCard , and cryptoWallet from the request. This creates a “shell” identity that reserves the agentId and gives you a vault namespace to write to. You can provision channels for that agent later.

​
agentId uniqueness

Each agentId is unique per account. Attempting to create a second identity with the same agentId returns an error.

​
Response shape

A successful create_agent_identity call returns a JSON object. Fields are omitted if the corresponding channel was not provisioned or if provisioning failed. 
{
  "emailAddress": "myagent@acme.agentmail.to",
  "emailId": "inbox_01abc",
  "phoneNumber": "+14155550123",
  "virtualCard": {
    "pan": "4111111111111111",
    "cvv": "123",
    "exp_year": "2027",
    "exp_month": "09",
    "token": "tok_01xyz"
  }
}
If a channel fails to provision, the response includes a corresponding error field (emailErrorMessage, phoneErrorMessage, virtualCardErrorMessage) alongside any channels that did succeed. 
{
  "emailAddress": "myagent@acme.agentmail.to",
  "emailId": "inbox_01abc",
  "virtualCardErrorMessage": "Error creating virtual card: insufficient funds"
}