Agent Quickstart

This path is optimized for AI agents and scripted checkers.

For a runnable acceptance check that starts from /llms.txt, use the Discoverability Smoke Test or run npm run smoke:agent.

0. What you need

A publicly reachable webhook URL for local tests (e.g. https://example.com/webhook).
The ability to make a copy-paste curl request from a shell.

1. Register a sandbox merchant

As of BDT-542 (deployed), registering a sandbox merchant is a four-step flow — email verification, confirm code, proof-of-work, then register — and fails closed unless your email/domain is allowlisted or you supply an invitation token obtained out-of-band (consumer webmail like gmail.com is not trusted by default). Do not skip straight to the last call below; it will not work standalone. Full steps, the proof-of-work solver, and the trust-gate explanation: Register a merchant.

# 1. Request email verification
curl -X POST https://api.plaidly.io/v1/merchants/email-verification \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]"}'
# -> {"registration_intent_id": "...", "expires_at": "..."}

# 2. Confirm the code delivered to that email
curl -X POST https://api.plaidly.io/v1/merchants/email-verification/confirm \
  -H "Content-Type: application/json" \
  -d '{"registration_intent_id": "...", "code": "123456"}'

# 3. Request (and solve) a proof-of-work challenge — see the register-merchant recipe for the solver
curl -X POST https://api.plaidly.io/v1/merchants/registration-proof-of-work \
  -H "Content-Type: application/json" \
  -d '{"registration_intent_id": "..."}'

# 4. Register
curl -X POST https://api.plaidly.io/v1/merchants \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Agent Quickstart Merchant",
    "sandbox": true,
    "webhook_url": "https://example.com/webhook",
    "idempotency_key": "agent-quickstart-01",
    "registration_intent_id": "...",
    "proof_of_work_challenge_id": "...",
    "proof_of_work_nonce": "..."
  }'

Save the api_key and webhook_secret from the final response.

2. Open sandbox context (2 minutes)

Use test endpoints to avoid real funds:

curl https://api.plaidly.io/v1/sandbox/faucets

Use the faucet list only as guidance for chains you want to test.

3. Create a stablecoin session (4 minutes)

Create a sandbox session with the merchant API key.

curl -X POST https://api.plaidly.io/v1/payment_sessions \
  -H "X-API-Key: <API_KEY_FROM_STEP_1>" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 0.0015,
    "expires_in": "30m",
    "metadata": {
      "source": "agent-quickstart"
    },
    "paymentMethod": {
      "methodID": 0,
      "chain": "solana",
      "token": "USDC",
      "network": "testnet"
    }
  }'

Save session_id from the response.

4. Trigger and finish payment in sandbox (2 minutes)

Simulate a confirmed payment without broadcasted chain activity:

curl -X POST https://api.plaidly.io/v1/payment_sessions/<SESSION_ID>/simulate

Check completion:

curl https://api.plaidly.io/v1/payment_sessions/<SESSION_ID>

5. Verify webhook reception (2 minutes)

Receive a signed payload with headers:

X-Plaidly-Event (event type)
X-Plaidly-Signature (t=<unix>,v1=<hex>)

Use webhook verification as the final guard before marking fulfillment complete.

6. Deliverable checklist

By the end of this flow you should have:

a sandbox session ID
a deposit address in the created session
a simulated completion event
a tested webhook signature check

Next docs:

Agent Quickstart

On this page