Skip to main content

Agent-TS Tools

The Agent uses OpenAI function calling with 20 tools organized into 5 categories.

Tool Categories​

CategoryToolsPurpose
Registration2User registration and status
KYC2Document upload and verification
Wallet6Balance, transfers, statements
Cards6Card management operations
Agent4Agent/merchant operations

Registration Tools​

check_user_registration​

Check if a phone number is registered as subscriber or agent.

{
  name: "check_user_registration",
  parameters: {
    phoneE164: string  // E.164 format phone number
  }
}

Returns: Registration status, user type, KYC level

register_subscriber​

Register a new subscriber account.

{
  name: "register_subscriber",
  parameters: {
    phoneE164: string,   // Phone number
    firstName: string,   // First name
    lastName: string,    // Last name
    pin: string          // 4-digit PIN
  }
}

KYC Tools​

upload_kyc_image​

Upload and validate a KYC document image.

{
  name: "upload_kyc_image",
  parameters: {
    phoneE164: string,  // User phone
    side: "front" | "back"  // ID side
  }
}
Note

Image data is passed via message context, not as a parameter.

upgrade_kyc​

Complete KYC upgrade after both ID sides are validated.

{
  name: "upgrade_kyc",
  parameters: {
    phoneE164: string,
    confirm: boolean  // User confirmation
  }
}

Wallet Tools​

check_balance​

Check wallet balance. Requires PIN.

{
  name: "check_balance",
  parameters: {
    phoneE164: string,  // User phone
    pin: string         // 4-digit PIN (REQUIRED)
  }
}

Returns: { balance: number, currency: string }

get_transactions​

Get transaction history. Requires PIN.

{
  name: "get_transactions",
  parameters: {
    phoneE164: string,
    pin: string,
    limit?: number  // Default: 10
  }
}

initiate_transfer​

P2P transfer to another user's card. Requires PIN.

{
  name: "initiate_transfer",
  parameters: {
    senderPhoneE164: string,     // Sender phone
    recipientCardSerial: string, // Recipient card (e.g., "CARD0005")
    amount: number,              // Amount in SLE
    pin: string                  // Sender's PIN
  }
}

get_account_limits​

Get transaction limits based on KYC level.

{
  name: "get_account_limits",
  parameters: {
    phoneE164: string
  }
}

Returns: Single transaction, daily, monthly limits

change_subscriber_pin​

Change subscriber's PIN. Requires old PIN.

{
  name: "change_subscriber_pin",
  parameters: {
    phoneE164: string,
    oldPin: string,  // Current PIN
    newPin: string   // New PIN
  }
}

request_account_statement​

Generate and send PDF account statement.

{
  name: "request_account_statement",
  parameters: {
    phoneE164: string,
    startDate: string,  // YYYY-MM-DD
    endDate: string     // YYYY-MM-DD
  }
}

Card Tools​

get_user_cards​

List all cards linked to user.

{
  name: "get_user_cards",
  parameters: {
    phoneE164: string
  }
}

Link a new card to account.

{
  name: "link_card",
  parameters: {
    phoneE164: string,
    cardSerial: string,
    pin: string
  }
}

create_child_card​

Create a child card with spending limits.

{
  name: "create_child_card",
  parameters: {
    phoneE164: string,
    parentCardSerial: string,
    childCardSerial: string,
    childName: string,
    dailyLimit: number,
    parentPin: string,
    childPin: string
  }
}

change_child_card_pin​

Change PIN for a child card.

{
  name: "change_child_card_pin",
  parameters: {
    phoneE164: string,
    cardSerial: string,
    parentPin: string,
    newChildPin: string
  }
}

block_card​

Block a card.

{
  name: "block_card",
  parameters: {
    phoneE164: string,
    cardSerial: string,
    pin: string,
    reason?: string
  }
}

unblock_card​

Unblock a blocked card.

{
  name: "unblock_card",
  parameters: {
    phoneE164: string,
    cardSerial: string,
    pin: string
  }
}

Agent Tools​

check_agent_balance​

Check agent float balance. Requires PIN.

{
  name: "check_agent_balance",
  parameters: {
    phoneE164: string,
    pin: string
  }
}

agent_cash_in​

Perform cash-in for a subscriber. Requires PIN.

{
  name: "agent_cash_in",
  parameters: {
    agentPhoneE164: string,
    subscriberPhoneE164: string,
    amount: number,
    pin: string
  }
}

transfer_to_sub_agent​

Transfer float to sub-agent. Requires PIN.

{
  name: "transfer_to_sub_agent",
  parameters: {
    fromAgentPhone: string,
    toAgentPhone: string,
    amount: number,
    pin: string
  }
}

change_agent_pin​

Change agent's PIN. Requires old PIN.

{
  name: "change_agent_pin",
  parameters: {
    phoneE164: string,
    oldPin: string,
    newPin: string
  }
}

Security Notes​

Warning

PIN Requirements: Most financial operations require the user's 4-digit PIN. The agent is instructed to always ask for PIN before calling these functions.

Warning

Phone Validation: The phoneE164 parameter must match the texting user's phone number. The agent will not accept requests to operate on different phone numbers.

Next Steps​

API Endpoints

REST endpoint documentation

KYC Validation

Document validation details