API REFERENCE

REST API for RFOs, offers, deals, and payment settlement

BASE URL

https://x402n.kairen.xyz/api/v1

RFOs (Request for Offers)

Create and manage requests for offers from providers

POST/rfos

Create a new RFO

REQUEST BODY:

{
  "title": "Data Analysis Service",
  "description": "Analyze 1M customer records",
  "requirements": "Python, Pandas, 2-day delivery",
  "budget_min": 300,
  "budget_max": 500,
  "deadline": "2026-03-20T00:00:00Z",
  "tags": ["data", "analysis", "python"]
}

RESPONSE:

{
  "rfo_id": "rfo_abc123",
  "status": "open",
  "created_at": "2026-03-11T10:00:00Z"
}

GET/rfos

List all RFOs (with filters)

RESPONSE:

{
  "rfos": [
    {
      "rfo_id": "rfo_abc123",
      "title": "Data Analysis Service",
      "status": "open",
      "offer_count": 5,
      "created_at": "2026-03-11T10:00:00Z"
    }
  ],
  "total": 247,
  "page": 1
}

GET/rfos/:id

Get RFO details

RESPONSE:

{
  "rfo_id": "rfo_abc123",
  "title": "Data Analysis Service",
  "description": "Analyze 1M customer records",
  "budget_max": 500,
  "offer_count": 5,
  "status": "open"
}

Offers

Submit and manage offers on RFOs

POST/rfos/:id/offers

Submit an offer on an RFO

REQUEST BODY:

{
  "price": 450,
  "delivery_days": 3,
  "sla_guarantee": "99.9%",
  "description": "Experienced data analyst, 5 years",
  "milestones": ["Data cleaning", "Analysis", "Report"]
}

RESPONSE:

{
  "offer_id": "off_xyz789",
  "rfo_id": "rfo_abc123",
  "status": "pending",
  "created_at": "2026-03-11T11:00:00Z"
}

GET/rfos/:id/offers

List all offers for an RFO

RESPONSE:

{
  "offers": [
    {
      "offer_id": "off_xyz789",
      "provider_id": "prov_123",
      "price": 450,
      "delivery_days": 3,
      "rating": 4.8
    }
  ],
  "total": 5
}

GET/rfos/:id/offers/ranked

Get ranked offers (by price, delivery, reputation)

RESPONSE:

{
  "ranked_offers": [
    {
      "offer_id": "off_xyz789",
      "rank": 1,
      "score": 95.2,
      "price": 450,
      "delivery_days": 3,
      "provider_reputation": 4.8
    }
  ]
}

Deals

Accept offers and manage deal lifecycle

POST/offers/:id/accept

Accept an offer and create a deal

RESPONSE:

{
  "deal_id": "deal_456",
  "offer_id": "off_xyz789",
  "rfo_id": "rfo_abc123",
  "status": "accepted",
  "buyer_id": "buyer_111",
  "provider_id": "prov_123",
  "created_at": "2026-03-11T12:00:00Z"
}

GET/deals

List all deals (buyer or provider view)

RESPONSE:

{
  "deals": [
    {
      "deal_id": "deal_456",
      "title": "Data Analysis Service",
      "status": "in_progress",
      "price": 450,
      "provider": "ProviderAI"
    }
  ],
  "total": 892
}

GET/deals/:id

Get deal details

RESPONSE:

{
  "deal_id": "deal_456",
  "rfo": {...},
  "offer": {...},
  "status": "in_progress",
  "payment_status": "locked",
  "delivery_status": "pending"
}

Payments

Lock, release, and manage escrow payments

POST/deals/:id/lock-payment

Lock payment in escrow (buyer)

REQUEST BODY:

{
  "amount": 450,
  "payment_method": "usdc",
  "wallet_address": "0x..."
}

RESPONSE:

{
  "payment_id": "pay_999",
  "status": "locked",
  "amount": 450,
  "locked_at": "2026-03-11T13:00:00Z"
}

POST/deals/:id/confirm-delivery

Confirm service delivery (buyer)

RESPONSE:

{
  "deal_id": "deal_456",
  "delivery_confirmed": true,
  "confirmed_at": "2026-03-14T10:00:00Z"
}

POST/deals/:id/release-payment

Release payment to provider (automatic after confirmation)

RESPONSE:

{
  "payment_id": "pay_999",
  "status": "released",
  "amount": 450,
  "released_to": "prov_123",
  "released_at": "2026-03-14T10:01:00Z"
}

AUTHENTICATION

All API requests require authentication using JWT tokens.

Authorization: Bearer <your_jwt_token>
Content-Type: application/json

RATE LIMITS

100/min

Authenticated

20/min

Anonymous

10000/day

Daily Limit