Agent API reference

Base URL: https://api.rampwire.app

Authentication

Authorization: Bearer rk_live_<48 hex chars>

Keys are issued via POST /api/admin/agent-keys (admin bearer). Revoked keys return 403.

---

POST /api/v1/pay

Create a programmatic payment — order is created in matched / claimed state with LP and amounts.

Auth	Agent API key
Rate limit	~30 POSTs / 60s / IP (sliding window)

Headers (optional)

Header	Purpose
Idempotency-Key	Deduplicate retries (also idempotency-key, idempotency_key)

Body (JSON)

Field	Type	Required	Notes
amount	number	yes	Fiat amount > 0
currency	string	yes	Must have active LP rate
recipient	string	yes	Destination (e.g. MSISDN)
user_id	number	yes	Existing user id
recipient_name	string	no	Display / compliance
method	string	no	Default mobile_money
callback_url	string	no	HTTPS webhook
crypto_symbol	string	no	Default usdt
crypto_chain	string	no	Default trx
rate_lock_id	string	no	Prior /api/rate lock id

Response 201

Field	Type
payment_id	string
order_id	number
status	string (matched)
crypto_required	{ amount, symbol, chain }
fiat_delivery	{ amount, currency, recipient, recipient_name, method }
rate	string (human label)
deposit_address	string or null
lp	{ id, rate }
callback_url	string or null
expires_at	ISO string
track_url	string

curl

export AGENT_KEY='rk_live_0123456789abcdef0123456789abcdef0123456789ab'

curl -sS -D - -X POST 'https://api.rampwire.app/api/v1/pay' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ${AGENT_KEY}" \
  -H 'Idempotency-Key: ref-001' \
  -d '{
    "amount": 5000,
    "currency": "KES",
    "recipient": "254712345678",
    "recipient_name": "Jane Wanjiku",
    "crypto_symbol": "usdt",
    "crypto_chain": "trx",
    "user_id": 42,
    "callback_url": "https://example.com/hooks/rampwire"
  }'

Errors

Status	Body / meaning
400	Invalid JSON, Zod error + Validation failed, missing pricing, bad user_id, bad rate_lock_id
403	Agent API key required / invalid key
404	No LP available for {currency}
429	Too many requests

Idempotent replay 200

Returns stored snapshot with idempotent_replay: true and masked recipient in fiat_delivery (use first response for full details).

---

GET /api/v1/status/:orderId

Auth	Agent

Response 200

{
  "order_id": 10042,
  "status": "fiat_sent",
  "amount_fiat": 5000,
  "currency": "KES",
  "crypto_symbol": "usdt",
  "crypto_amount": 38.812345,
  "tx_hash": null,
  "created_at": "2026-05-03T12:34:56.000Z",
  "completed_at": null
}

curl -sS 'https://api.rampwire.app/api/v1/status/10042' \
  -H "Authorization: Bearer ${AGENT_KEY}"

Errors: 404 {"error":"Not found"}; 403 bad key.

---

POST /api/v1/confirm/:orderId

Auth	Agent

Marks fiat_sent → confirmed server-side.

Body: {} optional.

Response 200: { "status": "confirmed" }

curl -sS -X POST 'https://api.rampwire.app/api/v1/confirm/10042' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ${AGENT_KEY}" \
  -d '{}'

---

POST /api/v1/settle/:orderId

Auth	Agent

Body

{ "tx_hash": "a1b2…" }

Response 200

{
  "status": "crypto_verify_pending",
  "message": "Transaction verification in progress",
  "order_id": 10042
}

curl -sS -X POST 'https://api.rampwire.app/api/v1/settle/10042' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ${AGENT_KEY}" \
  -d '{"tx_hash":"a1b2c3d4e5f6789exampleTrxTxHash0123456789abcdef"}'

Errors: 400 missing tx_hash; 409 order not confirmed.

---

Admin: agent key lifecycle

All require:

Authorization: Bearer <ADMIN_API_KEY>

POST /api/admin/agent-keys

Body: { "name"?: string, "integrator_name"?: string }

Response 201: { id, api_key, warning }

GET /api/admin/agent-keys

Response 200: list of { id, name, integrator_name, rate_limit, is_active, created_at, last_used_at }

DELETE /api/admin/agent-keys/:id

Soft-deactivates key — 204-style {"ok":true} in implementation.

curl -sS -X POST 'https://api.rampwire.app/api/admin/agent-keys' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_ADMIN_API_KEY' \
  -d '{"name":"dev","integrator_name":"ACME"}'

---

Operational notes

• CORS allows browser calls only from configured Rampwire web origins; agents should call from servers.
• Webhooks require operator coordination on WEBHOOK_SECRET — see Webhooks.
• User creation is outside /api/v1/* — use product auth routes or admin flows before paying.

See also Agent API guide and Errors.