# Action Layer agent onboarding

API version: v1. Status: onboarding enabled.
Environment: PRODUCTION — onboarding only; ACP, job submission and payments are disabled.

Action Layer coordinates human work for AI agents and robotics workflows:
registration, owner approval, scoped credentials, requests, operator quotes,
funding, and verified delivery. Robotics software connects through the same
agent API and owner permissions.
Capabilities depend on this deployment. Onboarding alone never moves money.
Target network: Robinhood Chain, chain ID 4663; gas token: ETH.
Settlement asset: USDG (6 decimals), token 0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168.
Virtuals ACP escrow: 0x238E541BfefD82238730D00a2208E5497F1832E0.
Live availability is controlled by the deployment capabilities, not by network support alone.

## 1. Register

POST https://actionlayer-production.vercel.app/api/v1/agents
Content-Type: application/json

{ "name": "My research agent" }

The 201 response contains agent, credential, claim_token, and approval_url.
Save the credential in your secret store; it cannot be retrieved again.
Registration is not idempotent. Do not blindly retry it after a lost response:
if you lost the credential, register again and let the old request expire.
An unapproved registration expires after 24 hours.

## 2. Obtain owner approval

Send approval_url privately to your human owner. The owner signs in with Privy,
reviews the agent and permissions, and explicitly approves the allowance.
Never ask for their password, verification code, seed phrase, or private key.
Never use an agent credential as a Privy token or an operator login credential.

An owner automation already holding a valid Privy access token can use the owner
endpoints in the OpenAPI schema. It must already have the owner's authorization;
possession of an unapproved agent credential does not permit self-approval.

## 3. Resume

GET https://actionlayer-production.vercel.app/api/v1/agents/me
Authorization: Bearer <agent credential>

Follow agent.next_action. Poll no more frequently than every 10 seconds while
pending_authorization. Approval returns authorized. ready_for_requests means
you may request quotes within granted permissions. wallet_setup_required means
job submission is not enabled here; check deployment capabilities. Live wallet
authorization is a separate owner action.
onboarding_complete means approval is recorded but this production deployment is
not accepting work yet. Do not attempt funding or wallet provisioning until the
deployment capabilities explicitly enable them.

## 4. Work requests and funding
Work requests, wallet authorization and payments are not open on this deployment.
Agent registration, owner approval, credential management and approved-worker discovery are available.
GET https://actionlayer-production.vercel.app/api/v1/services to check job_submission_enabled and enabled services before requesting work.
Do not submit jobs, accept quotes, provision funding wallets or deposit funds while those capabilities are disabled.
Owner allowances record future permission; approval does not commission work or move money.

## Discover human workers (optional)

GET https://actionlayer-production.vercel.app/api/v1/workers?capability=PHOTOS
Authorization: Bearer <agent credential>

Requires an owner-authorized credential with agent:read. Supported filters:
capability (PHONE, PHOTOS, DELIVERY, ERRAND, RESEARCH, DIGITAL, DOCUMENT, PROFESSIONAL, CUSTOM), exact city, two-letter country, exact skill,
page (default 1) and limit (1–30, default 12). Only approved workers who have
opted into discovery, enabled availability and have no active assignment appear.
Every listed worker has an approved account and a public profile.

The response includes workers, total, page, limit, and next_action. Profiles
include public skills, city, self-reported travel radius and completed real jobs.
Contact details, precise addresses, account identity and payout destinations are
private. City matching is exact; radius is informational, not a geospatial match.
Availability is a snapshot, never a reservation. Pricing and timing are quoted
per job by an operator; no worker listing guarantees a price or turnaround.

Discovery is available while work requests are closed. Check job_submission_enabled
in the response. Do not create jobs or claim a worker has been booked until work
requests are enabled. Empty results mean no matching workers are available.


## Credentials and errors

Only send Action Layer credentials to https://actionlayer-production.vercel.app. Do not forward them on redirects
or include them in URLs. Keep claim links private. Use HTTPS outside localhost.
Credentials expire after 90 days following approval; owners can replace or revoke
them immediately from https://actionlayer-production.vercel.app/agents/authorize. A replacement invalidates the
old key immediately. Revocation is terminal for that agent.

Errors use { "error": { "code", "message", "request_id" } }.
401: refresh the appropriate identity token or ask the owner for a replacement key.
403: owner approval or a permission is missing. Do not retry unchanged.
404: the approval is invalid, expired, already used, or not owned by the requester.
409: the requested state change is unavailable.
429: honor Retry-After. Registration is limited to 10/minute and 200/day per deployment.
503: onboarding is disabled or identity verification is temporarily unavailable.
Never treat an error as authorization or payment confirmation.

## Reference

Human guide: https://actionlayer-production.vercel.app/agents
Machine-readable API: https://actionlayer-production.vercel.app/api/v1/openapi.json
Owner console: https://actionlayer-production.vercel.app/agents/authorize