Agent API guide (B2B integrators)

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

Agent calls use API keys that start with rk_live_:

http

Authorization: Bearer rk_live_0123456789abcdef0123456789abcdef0123456789ab

All curl examples below use placeholders — substitute real secrets and ids.

1. Get an API key (admin only)

Keys are minted with the admin API (requires ADMIN_API_KEY on the server, passed as a normal Bearer token — not the agent key).

POST /api/admin/agent-keys

bash

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":"acme-prod","integrator_name":"ACME Payments"}'

Response 201

json

{
  "id": 3,
  "api_key": "rk_live_0123456789abcdef0123456789abcdef0123456789ab",
  "warning": "Store this key securely; it will not be shown again."
}

GET /api/admin/agent-keys lists metadata (no raw key).
DELETE /api/admin/agent-keys/{id} deactivates a key.

2. Create a payment — `POST /api/v1/pay`

Auth: Agent API key

Required body fields

Field	Example	Notes
`amount`	`5000`	Fiat amount (> 0)
`currency`	`"KES"`	Must match an active LP rate
`recipient`	`"254712345678"`	Mobile money / account id you are paying
`user_id`	`42`	Existing Rampwire user (created via product auth first)
`recipient_name`	`"Jane W."`	Optional
`crypto_symbol`	`"usdt"`	Optional; defaults `usdt`
`crypto_chain`	`"trx"`	Optional; defaults `trx`
`callback_url`	`"https://example.com/hooks/rampwire"`	Optional webhook target
`method`	`"mobile_money"`	Optional
`rate_lock_id`	`"rl_…"`	Optional quote lock

Example

bash

export AGENT_KEY='rk_live_0123456789abcdef0123456789abcdef0123456789ab'

curl -sS -X POST 'https://api.rampwire.app/api/v1/pay' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ${AGENT_KEY}" \
  -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",
    "method": "mobile_money"
  }'

Response 201 (abridged)

json

{
  "payment_id": "pay_1746275096123_a1b2c3",
  "order_id": 10042,
  "status": "matched",
  "crypto_required": {
    "amount": "38.812345",
    "symbol": "USDT",
    "chain": "trx"
  },
  "fiat_delivery": {
    "amount": 5000,
    "currency": "KES",
    "recipient": "254712345678",
    "recipient_name": "Jane Wanjiku",
    "method": "mobile_money"
  },
  "rate": "1 USDT = 128.83 KES",
  "deposit_address": "TXYZExampleTronReceiveAddressRampwire42",
  "lp": { "id": 12, "rate": 128.9 },
  "callback_url": "https://example.com/hooks/rampwire",
  "expires_at": "2026-05-03T14:34:56.000Z",
  "track_url": "https://rampwire.app/orders/10042"
}

Semantics

payment_id: correlation string for support (not always the idempotency key).
order_id: primary key for status / confirm / settle.
deposit_address / crypto_required: send crypto per your integration.
rate / lp.rate: human-readable implied price versus the LP’s rate_usd.

Common errors: 400 validation or unknown user_id; 404 no LP for currency; 403 bad agent key.

3. Track payment — `GET /api/v1/status/:orderId`

bash

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

Response 200

json

{
  "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
}

4. Confirm fiat delivery — `POST /api/v1/confirm/:orderId`

Advances fiat_sent → confirmed when the server accepts the transition.

bash

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

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

5. Settle — `POST /api/v1/settle/:orderId`

Submit the user’s on-chain tx_hash after confirmed.

bash

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"}'

Response 200

json

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

Errors: 400 missing tx_hash; 409 order not in confirmed.

6. Webhooks

When callback_url is set, Rampwire POSTs JSON on lifecycle changes. Payload, signature, and retries: Webhooks.

Highlights

Header X-Rampwire-Signature: hex-encoded HMAC-SHA256 of the raw JSON body using WEBHOOK_SECRET configured server-side.
Event envelope uses "event": "order.status_changed" with a status field describing the transition (claimed, fiat_sent, confirmed, completed, cancelled, disputed, …).

7. Idempotency

Send a unique key on POST /api/v1/pay:

http

Idempotency-Key: pay-run-20260503-001

Accepted header variants: Idempotency-Key, idempotency-key, idempotency_key.

Within the retention window, duplicate POSTs return 200 with the same logical payload as the first order created for that key.

bash

curl -sS -X POST 'https://api.rampwire.app/api/v1/pay' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ${AGENT_KEY}" \
  -H 'Idempotency-Key: acme-mpesa-kenya-20260503-001' \
  -d '{"amount":5000,"currency":"KES","recipient":"254712345678","user_id":42}'

8. Rate limiting

POST /api/v1/pay is limited to 30 requests per rolling 60 seconds per client IP (sliding window). Responses may include:

json

{ "error": "Too many requests" }

with HTTP 429. Back off exponentially and reuse Idempotency-Key for safe retries.

9. Full example — KES 5,000 M-Pesa style payment

Prerequisites: user_id=42 already exists, you hold a valid rk_live_ key, and an LP publishes KES rates.

bash

#!/usr/bin/env bash
set -euo pipefail
API='https://api.rampwire.app'
AGENT_KEY='rk_live_REPLACE_ME'
USER_ID=42

PAY="$(curl -sS -X POST "${API}/api/v1/pay" \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ${AGENT_KEY}" \
  -H "Idempotency-Key: demo-kes-5k-$(date +%s)" \
  -d "{
    \"amount\": 5000,
    \"currency\": \"KES\",
    \"recipient\": \"254712345678\",
    \"recipient_name\": \"M-Pesa Customer\",
    \"method\": \"mobile_money\",
    \"crypto_symbol\": \"usdt\",
    \"crypto_chain\": \"trx\",
    \"user_id\": ${USER_ID},
    \"callback_url\": \"https://example.com/hooks/rampwire\"
  }")"

ORDER_ID="$(echo "$PAY" | jq -r '.order_id')"
echo "Created order ${ORDER_ID}"
echo "$PAY" | jq .

echo "--- poll status ---"
curl -sS "${API}/api/v1/status/${ORDER_ID}" \
  -H "Authorization: Bearer ${AGENT_KEY}" | jq .

# After LP sends fiat and you verified receipt off-platform:
curl -sS -X POST "${API}/api/v1/confirm/${ORDER_ID}" \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ${AGENT_KEY}" \
  -d '{}' | jq .

# After user broadcasts USDT from their wallet:
curl -sS -X POST "${API}/api/v1/settle/${ORDER_ID}" \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ${AGENT_KEY}" \
  -d '{"tx_hash":"REPLACE_WITH_REAL_TRON_TXID"}' | jq .

Reference

Endpoint-by-endpoint tables: Agent API reference.

Legal and support topics: contact your Rampwire operator for WEBHOOK_SECRET alignment and admin access.

Agent API guide (B2B integrators) ​

1. Get an API key (admin only) ​

2. Create a payment — POST /api/v1/pay ​

3. Track payment — GET /api/v1/status/:orderId ​

4. Confirm fiat delivery — POST /api/v1/confirm/:orderId ​

5. Settle — POST /api/v1/settle/:orderId ​

6. Webhooks ​

7. Idempotency ​

8. Rate limiting ​

9. Full example — KES 5,000 M-Pesa style payment ​

Reference ​

Agent API guide (B2B integrators)

1. Get an API key (admin only)

2. Create a payment — `POST /api/v1/pay`

3. Track payment — `GET /api/v1/status/:orderId`

4. Confirm fiat delivery — `POST /api/v1/confirm/:orderId`

5. Settle — `POST /api/v1/settle/:orderId`

6. Webhooks

7. Idempotency

8. Rate limiting

9. Full example — KES 5,000 M-Pesa style payment

Reference