Shadow Number

intent

use this skill when you need a disposable phone number to receive SMS verification codes during website signup. the skill calls the shadow API to provision a real temporary number for your chosen service and country, navigates to the signup flow, polls for incoming OTP codes, and enters them to complete verification. x402 payment (roughly $0.10 USDC on Base) is handled automatically by your agent wallet when the API returns a 402 response.

inputs

environment variables:

• SHADOW_WALLET_KEY: your agent's private key for x402 payment authorization on Base network. must have sufficient USDC balance to cover purchases (~$0.10 per number).
• SHADOW_API_URL: api endpoint root. defaults to https://extraordinary-charisma-production.up.railway.app.

parameters:

• country (required): two-letter country code (US, GB, FR, DE, IN, BR, PH, ID, NG, RU, UA, PL, CA, AU, MX, or 60+ others). determines phone number prefix and regional availability.
• service (required): service code string (opt1, opt2, opt7, opt15, opt22, etc.). maps to the target website. see service code table below.
• orderId (required for steps 4-5): returned from the buy request. identifies the specific number and OTP session.

service codes (common):

for services not listed, search the service name or ask the API - most major platforms are supported.

external connections:

• shadow API (x402 gated). your agent must have x402 payment capability enabled in its wallet config.
• target website (browser interaction). you or your agent must be able to navigate and interact with the signup form.

procedure

step 1: request temp number

• input: country code (e.g. "US"), service code (e.g. "opt7" for Gmail).
• make POST request to {SHADOW_API_URL}/api/smspva/buy.
• request body:

  {
    "country": "US",
    "service": "opt7"
  }
  

• if server returns HTTP 402 (payment required), your agent wallet automatically pays ~$0.10 USDC on Base, then retries the request.
• output on success (200): json response containing phoneNumber (e.g. "14155552671"), orderId (e.g. "abc123"), and orderExpireIn (seconds until expiry, typically 300-600).

step 2: format and enter number on website

• input: phoneNumber from step 1, country code.
• open the target website signup or phone verification page in a browser.
• construct the full international number: +{countryCode}{phoneNumber}. example: US country code is 1, so "+14155552671".
• enter this number into the phone field.
• click the "send code", "verify", "get OTP", or equivalent button.
• wait for page confirmation that SMS was requested (do not proceed until the website acknowledges the request).
• output: browser page shows "code sent" or waiting state.

step 3: poll for incoming OTP

• input: orderId from step 1.
• make GET request to {SHADOW_API_URL}/api/smspva/otp/{orderId}.
• poll every 15 seconds. do not poll faster (risk of rate limiting).
• continue polling until one of three outcomes: status 200 received, orderExpireIn reaches 0, or status 410 received.
• output on success (200): json response containing sms.code (the 4-6 digit OTP, e.g. "123456") and updated orderExpireIn.

step 4: enter OTP on website

• input: code from step 3 (sms.code).
• switch back to the browser tab from step 2.
• enter the OTP code into the verification input field.
• submit the form.
• output: website either confirms signup success or displays error.

decision points

if POST /buy returns 402 (payment required):

• your agent wallet automatically signs and submits an x402 payment transaction (~$0.10 USDC on Base).
• retry the buy request. if still 402, your wallet lacks sufficient USDC balance. top up and retry.

if POST /buy returns non-200 (e.g. 400, 429, 500):

• try a different country code or service code.
• if the same country and service consistently fail, the combination may be unsupported or temporarily unavailable. pick an alternate country and call buy again.

if GET /otp/{orderId} returns 202 (not yet received):

• wait 15 seconds and retry. the SMS is still in transit.
• this is normal. most codes arrive within 30-90 seconds.

if GET /otp/{orderId} returns 410 (order closed):

• the SMS window has closed or the order was explicitly cancelled.
• go back to step 1 and purchase a new number.

if orderExpireIn drops to 0 during polling:

• the order has expired. stop polling.
• go back to step 1 and purchase a new number with the same or different country.

if the website rejects or does not recognize the number:

• make PUT request to {SHADOW_API_URL}/api/smspva/refuse/{orderId} to mark the number as refused.
• go back to step 1 and purchase a new number (try a different country if the first one consistently fails).

if the website or service has blocked the number:

• make PUT request to {SHADOW_API_URL}/api/smspva/ban/{orderId} to mark the number as banned by that service.
• go back to step 1 and purchase a new number with a different country code.

output contract

on successful completion:

• the target website's signup flow confirms account creation (display of confirmation page, email sent notification, or auto-login).
• if automating with an agent, the final state should be: website returns HTTP 200+ and displays authenticated user dashboard or welcome message.

polling data structure (step 3 success):

{
  "statusCode": 200,
  "data": {
    "sms": {
      "code": "123456"
    },
    "orderId": "abc123",
    "orderExpireIn": 540
  }
}

phone number format:

• always +{countryCode}{phoneNumber} (e.g. +14155552671 for US).
• country code is 1 for US, 44 for GB, 33 for FR, etc.

file/state location:

• no files are generated. all state is transient (number, orderId, OTP) and expires after orderExpireIn seconds.
• if you need to log this, store the orderId, country, service, and timestamp of purchase for audit purposes.

outcome signal

• the website displays a success page (account created, logged in, or confirmation email sent).
• if polling via automation: the final HTTP response from the target website is 200-299 and contains user-facing confirmation text or a redirect to the authenticated dashboard.
• you should see the OTP code arrive in the shadow API response within 60-120 seconds of triggering the SMS on the website.
• if none of these occur within 10 minutes (orderExpireIn timeout), the skill has failed: purchase a new number and retry.

original author: clawhub. enriched to implexa standards.