POST /api/me/coins/gift

Account required · HTTP API reference

All endpoints · Authentication and retries · Download OpenAPI

Requires a signed-in account and permission to access this resource. Use identifiers returned by your own account's earlier requests.
Protected writes require an allowed Origin, the CSRF cookie and matching X-CSRF-Token header.
Send a fresh X-Request-Nonce and current X-Request-Timestamp on every attempt. Reuse an idempotency key only for the same logical action.

Request

Parameter	Location	Type and requirement
`x-idempotency-key`	header	string · optional Pattern: `^[A-Za-z0-9_-]{8,128}$`
`X-Request-Nonce`	header	string · required Generate a fresh nonce for every attempt. Pattern: `^[A-Za-z0-9_-]{16,128}$`
`X-Request-Timestamp`	header	string · required Current Unix seconds (10 digits) or milliseconds (13 digits). Pattern: `^(?:[0-9]{10}\|[0-9]{13})$`
`Origin`	header	string · required An origin allowed by this deployment.
`X-CSRF-Token`	header	string · required Must match the CSRF cookie issued to this browser.

Body · application/json

recipientUserId required · string | number

amount required · string | number

note optional · string

idempotencyKey optional · string

Example

Examples use fictional data. Replace identifiers with resources you can access. For account requests, cookies.txt must contain your own session; set CSRF_TOKEN to the matching CSRF cookie value where required.

Save as request.json

{
  "recipientUserId": "1",
  "amount": "1"
}

cURL (POSIX shell)

curl --include \
  --request POST \
  'https://api.weavers.app/api/me/coins/gift' \
  --cookie cookies.txt --cookie-jar cookies.txt \
  --header "X-Request-Nonce: $(openssl rand -hex 16)" \
  --header "X-Request-Timestamp: $(date +%s)" \
  --header 'Origin: https://weavers.app' \
  --header "X-CSRF-Token: ${CSRF_TOKEN}" \
  --header 'Content-Type: application/json' \
  --data-binary @request.json

Responses

200 · Successful response.

application/json

200 example · synthetic data

{
  "status": "sent",
  "gift": {
    "id": 1,
    "senderUserId": 1,
    "recipientUserId": 1,
    "amount": 1,
    "status": "failed",
    "idempotencyKey": "example-request-0001",
    "metadata": null,
    "createdAt": "2025-01-01T00:00:00.000Z",
    "updatedAt": "2025-01-01T00:00:00.000Z"
  },
  "balance": 1,
  "wallets": {
    "earned": 1,
    "promo": 1,
    "purchased": 1,
    "total": 1
  },
  "recipientBalance": null
}

View response model

status required · "sent" | "already_sent"

gift required · object

View gift model

id required · number

senderUserId required · number

recipientUserId required · number

amount required · number

status required · "failed" | "completed"

idempotencyKey required · string

metadata required · null | object

View metadata model

Variant 1: null

null

Variant 2: object

Additional fields: JSON value.

createdAt required · string

updatedAt required · string

Additional fields: JSON values.

balance required · number

wallets required · object

View wallets model

earned required · number

promo required · number

purchased required · number

total required · number

Additional fields: JSON values.

recipientBalance required · null | number

View recipientBalance model

Variant 1: null

null

Variant 2: number

number

Additional fields: JSON values.

400 · Invalid request.

application/json

400 example · synthetic data

{
  "error": "example"
}

View response model

Variant 1: object

error required · string

Additional fields: JSON values.

Variant 2: object

error required · "invalid_idempotency_key" | "invalid_amount" | "self_gift_not_allowed"

Additional fields: JSON values.

401 · Authentication is missing or invalid.

application/json

401 example · synthetic data

{}

View response model

Error envelopes can include resource-specific details. Check the status before reading these fields.

error optional · string

code optional · string

message optional · string

Additional fields: JSON values.

402 · Credits or entitlement required.

application/json

402 example · synthetic data

{
  "error": "example",
  "missing": 1,
  "balance": 1,
  "wallets": {
    "earned": 1,
    "promo": 1,
    "purchased": 1,
    "total": 1
  }
}

View response model

error required · string

missing required · number

balance required · number

wallets required · object

View wallets model

earned required · number

promo required · number

purchased required · number

total required · number

Additional fields: JSON values.

403 · Permission, origin or CSRF check failed.

application/json

403 example · synthetic data

{
  "error": "gifting_disabled"
}

View response model

error required · "gifting_disabled"

Additional fields: JSON values.

404 · Resource or enabled capability not found.

application/json

404 example · synthetic data

{
  "error": "recipient_not_found"
}

View response model

error required · "recipient_not_found"

Additional fields: JSON values.

429 · Rate limit reached; honor Retry-After when supplied.

application/json

429 example · synthetic data

{
  "error": "daily_cap_reached",
  "cap": 1,
  "used": 1,
  "remaining": 1
}

View response model

error required · "daily_cap_reached" | "monthly_cap_reached"

cap required · number

used required · number

remaining required · number

Additional fields: JSON values.

500 · Server failure.

application/json

500 example · synthetic data

{
  "error": "example"
}

View response model

Variant 1: object

error required · string

Additional fields: JSON values.