---
name: darksol-agentcomms
description: Use DARKSOL AgentComms to generate worldwide-access disposable virtual phone numbers, provision US-only premium durable phone lines, and check SMS messages through x402 payments on Base; includes required agent memory rules for saving provider, countryCode, and phoneNumber.
---

# DARKSOL AgentComms

AgentComms gives autonomous agents x402-gated worldwide-access disposable numbers, US-only premium durable lines, and SMS checks. Disposable SMS checks are live; premium durable messaging is rolling out over the next 72 hours.

Base URL: `https://acp.darksol.net`

## Current service note

AgentComms has two distinct tiers:

- **Disposable Zyla tier:** worldwide access where upstream inventory supports the requested country. Use `/countries` to discover country codes, then request `/numbers` with that `countryCode`.
- **Premium Telnyx durable tier:** **US-only** under the current Telnyx account limits. Use `countryCode: "US"` for premium search/provisioning. Premium lines cost `$10.00` USDC setup and last **3 months** unless the user renews before `expiresAt`.

Do not treat Telnyx premium limitations as applying to the disposable tier.

The disposable AgentComms number service is primarily intended for short-lived verification workflows worldwide: situations where an agent needs to provide a phone number, receive an SMS code, verify access or identity, and complete the task within roughly a 15-20 minute window. Use it for temporary verification, one-off SMS receipt, and similar short-session workflows.

For workflows that need a persistent phone identity, use the Telnyx premium durable line tier. Inbound SMS webhooks should be configured in Telnyx to POST to `https://acp.darksol.net/api/agentcomms/telnyx/webhook`. The webhook receiver persists to Vercel KV/Upstash when configured and falls back to ephemeral memory in local/dev environments.

Current Telnyx paid-account limits apply to the **premium durable tier only**: US local numbers only for this account, no 10DLC, no Toll-Free verification, no hosted messaging, 5 concurrent outbound calls, 10 outbound calls/hour, and 100 outbound calls/day. Treat outbound SMS as limited preview only. Do not use AgentComms for marketing blasts, bulk sends, spam, or hosted messaging use cases.

Bankr x402 endpoints:

- Numbers: `https://x402.bankr.bot/0x8f9fa2bfd50079c1767d63effbfe642216bfcb01/agentcomms-numbers`
- Messages: `https://x402.bankr.bot/0x8f9fa2bfd50079c1767d63effbfe642216bfcb01/agentcomms-messages`
- Premium durable US lines: `https://x402.bankr.bot/0x8f9fa2bfd50079c1767d63effbfe642216bfcb01/agentcomms-premium-lines`

## Pricing

- Generate/get disposable worldwide-access number: `$1.00` USDC on Base
- Generate/get disposable worldwide-access number for 10M+ DARKSOL holder wallet: `$0.50` USDC
- Search premium durable lines: `$0.05` USDC, free for 10M+ DARKSOL holder wallet
- Provision premium durable US line: `$10.00` USDC setup + provider rental/usage; **3-month term, renewal required before expiry**
- Check SMS messages: `$0.01` USDC
- Check SMS messages for 10M+ DARKSOL holder wallet: free

Holder minimum: `10,000,000` DARKSOL on Base.

## Critical memory rule

When any AgentComms number endpoint returns a number, persist these fields in your own memory/state:

```json
{
  "service": "darksol-agentcomms",
  "provider": "zyla",
  "durable": false,
  "countryCode": "1",
  "phoneNumber": "18578329806",
  "smsPhoneNumberParam": "578329806",
  "purpose": "short description of workflow/account/app",
  "createdAt": "ISO timestamp",
  "lastCheckedAt": null
}
```

Do **not** create a new number every time you need messages. Reuse the saved `provider` + `countryCode` + `phoneNumber`/`smsPhoneNumberParam` pair when polling `/api/agentcomms/messages`. Zyla disposable numbers can expire quickly and require removing the first 2 digits from the number returned by `/numbers`; the API returns `smsPhoneNumberParam` for you. Telnyx premium lines are durable for 3 months by default and should be reused until `expiresAt`; renew before expiry if the user wants to keep the same line.

## Workflow

1. If you do not know the country code, call:

```bash
curl https://acp.darksol.net/api/agentcomms/countries
```

2. Request a disposable Zyla number. This tier has worldwide access; choose the actual `countryCode` returned by `/countries` for non-US workflows:

```bash
curl -X POST https://acp.darksol.net/api/agentcomms/numbers \
  -H "Content-Type: application/json" \
  -d '{"countryCode":"1"}'
```

Or call the Bankr x402 wrapper directly:

```bash
curl -X POST https://x402.bankr.bot/0x8f9fa2bfd50079c1767d63effbfe642216bfcb01/agentcomms-numbers \
  -H "Content-Type: application/json" \
  -d '{"countryCode":"1"}'
```

If the response is `402`, pay using an x402-compatible client, then retry with the payment header.

3. Or search/provision a premium durable Telnyx line:

```bash
curl "https://acp.darksol.net/api/agentcomms/premium/search?provider=telnyx&countryCode=US&areaCode=857"
```

Then provision a selected number. This is the `$10` premium-line action: it creates a 3-month term and returns `expiresAt` / `renewalRequired`.

```bash
curl -X POST https://acp.darksol.net/api/agentcomms/premium/lines \
  -H "Content-Type: application/json" \
  -d '{"provider":"telnyx","phoneNumber":"+18575550123"}'
```

Bankr x402 wrapper for the same `$10` premium line action:

```bash
curl -X POST https://x402.bankr.bot/0x8f9fa2bfd50079c1767d63effbfe642216bfcb01/agentcomms-premium-lines \
  -H "Content-Type: application/json" \
  -d '{"provider":"telnyx","phoneNumber":"+18575550123"}'
```

4. Save the returned `provider`, `countryCode`, `phoneNumber`, `smsPhoneNumberParam` if present, and provider id immediately.

5. Check SMS messages:

```bash
curl "https://acp.darksol.net/api/agentcomms/messages?countryCode=1&phoneNumber=578329806"
```

For a premium Telnyx line:

```bash
curl "https://acp.darksol.net/api/agentcomms/messages?provider=telnyx&phoneNumber=%2B18575550123"
```

Telnyx inbound webhook URL for the messaging profile:

```text
https://acp.darksol.net/api/agentcomms/telnyx/webhook
```

If `TELNYX_WEBHOOK_SECRET` is configured, append `?secret=...` in Telnyx or send `x-agentcomms-webhook-secret`. Webhook storage is durable when `KV_REST_API_URL` + `KV_REST_API_TOKEN` or Upstash REST env vars are configured. Without those env vars it falls back to `memory_ephemeral`, which is only suitable for local smoke tests.

Or call the Bankr x402 wrapper directly:

```bash
curl "https://x402.bankr.bot/0x8f9fa2bfd50079c1767d63effbfe642216bfcb01/agentcomms-messages?countryCode=1&phoneNumber=578329806"
```

If the response is `402`, pay using x402 unless you have valid 10M+ DARKSOL holder proof.

## Holder access

For holder discounts/free SMS checks, send:

```http
x-darksol-wallet: 0xYourWallet
x-darksol-signature: signature
```

The wallet must hold at least `10,000,000` DARKSOL on Base.

Ask the service health endpoint for the current holder policy:

```bash
curl https://acp.darksol.net/api/agentcomms/health
```

## Backoff / polling

SMS checks bill per successful paid request unless a valid holder proof applies. Use reasonable backoff:

- First check: 5-10 seconds after requesting the code
- Then: 15s, 30s, 60s
- Stop after the workflow expires

Do not tight-loop.

## Safety

Use only for legitimate agent communication and verification workflows. Do not use for spam, harassment, fraud, account abuse, or bypassing platform restrictions. Treat SMS contents as sensitive and avoid durable logs of message bodies or verification codes.