API Quickstart

This flow resolves or creates a wallet account, creates an agent, and reads its state. Use the interactive API reference for the complete schemas and current operation details.

1. Authenticate the wallet

Create a SIWE message, have the user’s wallet sign it, and encode the message/signature pair as the token described in API authentication.

2. Resolve or create the user

Call loginWithWallet first. Send the wallet address in the JSON body and the signed token in Authorization. If the wallet has an account, the response contains user.userId. If the API returns NO_USER, create the account with the same wallet address and signed token:

POST /v1/users/login-with-wallet
Content-Type: application/json
Authorization: Signature <signature-token>

{"walletAddress":"0x..."}

POST /v1/users
Content-Type: application/json

{"walletAddress":"0x...","username":"...","signatureString":"<base64-signature-token>"}

createUser verifies signatureString from the request body; it does not use the Authorization header. A valid integrator X-Api-Key may be included to attribute the new account. referralCode is optional.

3. Create an agent

POST /v1/users/{userId}/agents
Content-Type: application/json
Authorization: Signature <signature-token>

The signed-in wallet must own the userId. Provide the required name and emoji; chain, base asset, type, and rule-preset fields and defaults are listed in Creating an agent via API.

4. Fund and activate it

Funding and deployment are separate from agent creation. For the current Vault Agent, follow Vault Agent API integration for the type-specific flow.

5. Read state

Use the type’s balance, position, activity, and statistics operations to verify the agent’s state after each lifecycle step.

Safe client behavior

• Validate the response before moving to the next step.
• Preserve transaction hashes and request IDs for support.
• Do not blindly retry mutations.
• Treat unsupported type/asset combinations as configuration errors.
• Keep signature tokens and API keys out of logs.